@xbyorange/mocks-server

Mocks Server

Mocks server with extensible fixtures groupables in predefined behaviors. Behavior can be changed using built-in CLI or REST API.

Table of contents

• Getting started
• Installation
• Usage
  • Interactive CLI
  • Rest Api
    • Programmatic usage
      • CLI
      • Server
    • Global usage
• Options
• Defining mocks

Getting Started

This package provides a server that simulates API behaviors. As input, it needs "fixtures", which are responses for specific uris, and "features", which are sets of "fixtures".

It also provide a built-in CLI and a REST API which allows to change the currently used "feature" in any moment simply making an http request.

Installation

npm i @xbyorange/mocks-server --save-dev

Usage

Interactive CLI

Add an script to your package.json file, including the path to your mocks folder:

"scripts": {
  "mocks-server" : "mocks-server --features=./mocks"
}

Now, you can start the mocks server CLI simply typing:

npm run mocks-server

REST API

The server includes a REST API that allows to change dinamically the current feature, change delay time, etc.

Available api resources are:

• GET /mocks/features Returns an array containing all available features.
• GET /mocks/features/current Returns current feature.
• PUT /mocks/features/current Set current feature.
  • Request body example: { "name": "feature-name" }
• GET /mocks/settings Return current server settings.
  • Response body example: { "delay": 0 }
• PUT /mocks/settings Change current server settings.
  • Request body example: { "delay": 3000 }

Programmatic usage

CLI

The interactive CLI can be instantiated and started programmatically:

const { Cli } = require("@xbyorange/mocks-server");

const startMyCli = () => {
  const cli = new Cli({
    port: 3200,
    log: "debug",
    watch: false
  });

  return cli.start();
};

startMyCli().catch(err => {
  console.log("Error starting CLI", err);
});

Cli ([options][,customQuitMethod])

For first argument options, please read the options chapter of this documentation. Available methods of an instance are:

• start () Inits the server in case it was stopped, adds the watch listeners, and renders main menu.
• initServer () Inits the server in case it was stopped, adds the watch listeners.
• stopListeningServerWatch () When server watch is active, the main menu will be displayed on file changes. This behavior can be deactivated using this method. This is useful when this CLI is loaded as a submenu of another CLI, for example.

Server

The server can be instantiated and started programmatically:

const { Server } = require("@xbyorange/mocks-server");

const startMyServer = () => {
  const server = new Server(path.resolve(__dirname, "mocks"), {
    port: 3200,
    log: "debug",
    watch: false
  });

  return server.start();
};

startMyServer().then(server => {
  console.log("Server started", server);
});

Server (featuresFolder [,options])

First argument is mandatory, and has to be a path to a folder containing "features". All files in the folder will be loaded recursively, including subfolders. For second argument options, please read the options chapter of this documentation.

Available methods of an instance are:

• start (). Starts the server.
• stop (). Stops the server.
• restart (). Stops the server, initializes it again (reloading features files), and starts it again.
• switchWatch (state <Boolean>). Enable or disable features files watch, depending of the received "state" value.

Available getters are:

• features. Returns loaded features object.
• watchEnabled. Current state of the features files watcher.
• error. When server has returned an error, or an error ocurred loading features, it is available in this property.
• events. Returns server events object. A "watch-reload" event is emitted when the server watch detects changes in any features file, and restarts the server.

Global usage

The mocks server can be used as a global dependency as well:

npm i @xbyorange/mocks-server -g

Now, you can start the built-in command line interface from anywhere, providing a path to a features folder:

mocks-server --features=./path-to-features

Options

• port <Number> Por number for the Server to be listening.
• host <String> Host for the server. Default is "0.0.0.0" (Listen to any local host).
• log <String> Logs level. Can be one of "silly", "debug", "verbose", "info", "warn", "error".
• watch <Boolean> Watch features folder, and restart server on changes. Default is true.
• feature <String> Selected feature when server is started.
• delay <Number Responses delay time in milliseconds.
• features Path as <String> Path to a folder containing features to be used by the server.
• recursive <Boolean> Load features recursively. Watch is not affected by this option, it is always recursive.
• cli <Boolean> Start interactive CLI. Default is true.

Defining mocks

The Mocks server handles two main concepts for defining mocks:

Features

Each feature consists in a set of "fixtures", which are server responses for specific uris.

Features are extensibles, so, you can have a "base" feature, which defines the standard behavior of the mocks server and responses for all api uris, and change this behavior creating new features that changes only responses for certain "uris". All features are extensible as well.

For creating a Feature, you have to use the mocks-server "Feature" class, providing an array of "fixtures" to it:

// Features file 1

const { Feature } = require("@xbyorange/mocks-server");

const fixtures = require("./fixtures");

const myFeature = new Feature([fixtures.uri_1_fixture, fixtures.uri_2_fixture]);

module.exports = {
  myFeature
};

Now, when loaded, the server will have available a "myFeature" feature, which contains two fixtures. You can add more features extending the first one and changing only the response for "uri_2", for example:

// Features file 2

const { myFeature } = require("./features");

const fixtures = require("./fixtures");

const myFeature2 = myFeature.extend([fixtures.uri_2_different_fixture]);

module.exports = {
  myFeature2
};

Now, server will have available "myFeature" and "myFeature2" features. And "myFeature2" will send a different response only for "uri_2" (supossing that "uri_2_fixture" and "uri_2_different_fixture" were defined with the same uri)

Fixtures

A "fixture" defines the response for an specific uri. It has to be an object containing properties:

• url uri as <String> Uri of the resource. It can contains expressions for matching dynamic uris. Read the route-parser documentation for further info about how to use dynamic routing.
• method <String> Method of the request. Defines to which method will response this fixture. Valid values are http request methods, such as "GET", "POST", "PUT", etc.
• response <Object> Defines the response that the Mocks Server will send to the request:
  • status <Number> Status code to send.
  • body <Object> Json object to send as body in the response.
• response <Function> Response can be defined as a function too. The function will receive the express request, response and next arguments, so you are free to handle the server request as you need.

// Fixtures file

const uri_1_fixture = {
  url: "/api/foo-uri",
  method: "GET",
  response: {
    status: 200,
    body: [
      {
        name: "foo-name"
      }
    ]
  }
};

const uri_2_fixture = {
  url: "/api/foo-uri-2/:id",
  method: "PUT",
  response: {
    status: 204
  }
};

const uri_2_different_fixture = {
  url: "/api/foo-uri-2/:id",
  method: "PUT",
  response: (req, res) => {
    res.status(404);
    res.send({
      message: `${req.params.id} was not found`
    });
  }
};

module.exports = {
  uri_1_fixture,
  uri_2_fixture,
  uri_2_different_fixture
};

Contributing

Contributors are welcome. Please read the contributing guidelines and code of conduct.