Remok

Remok is a simple record and replay capable mock server.

Features

• Records requests
• Replays recorded requests
• Small footprint (only two tiny dependencies)
• Works out of the box with zero config
• Uses a powerful hash logic to store mocks
• Written with future proof ECMAScript 2015 module syntax

Installation

Remok is available as the remok package on npm.

npm install --save-dev remok

How to use

API

const remok = require('remok');

const server = remok({
  server: {
    port: 3000,
  },
  mocks: {
    path: './mocks',
  },
  proxy: {
    target: 'https://some.api.tld',
  },
});

server.start();

CLI

$ remok --config ./remok.config.js

// remok.config.js
module.exports = {
  proxy: {
    target: 'https://some.api.tld',
  },
}

Test

You can test your setup by sending a request to the server:

curl http://localhost:3000/some/endpoint

Advanced usage

Manually creating a mock

Remok will always try to load a /path/to/mock/<METHOD>[email protected] file first, afterwards it searches for a /path/to/mock/<METHOD>.<REQUEST_HASH>.json file.

You can use the remok create-mock ./foo/GET CLI command in order to create a manual mock.

Activating the watch-mode mocks.watch: true will load new mocks without having to restart Remok.

Mock file structure

The following fields are required in a mock file:

{
  "time": "2018-01-01T00:00:00.000Z",
  "request": {
    "_hash": "requesthashvalue",
    "method": "GET",
    "path": "/foo/bar",
    "headers": {
      "key": "value"
    },
    "query": null,
    "body": null
  },
  "response": {
    "_hash": "responsehashvalue",
    "_time": null,
    "status": {
      "code": 201,
      "message": "custom status message"
    },
    "headers": {
      "key": "value"
    },
    "body": "I'm the response body!"
  }
}

History mode

🚧

API

remok([options])

Creates the Remok application.

| Property | Type | Default | Description | | ---------------- | ---------- | ------------------ | ---------------------------------------- | | verbose | boolean | true | Makes output more or less verbose | | | | | | | server.port | number | 3000 | Server port | | server.host | string | localhost | Server host | | | | | | | mocks.record | mixed | true | Whether to record mocks. Setting this option to overwrite will overwrite existing mocks. | | mocks.path | string | ./remok | Path used for storing recorded mocks | | mocks.history🚧 | boolean | false | Use the history mode | | mocks.watch | boolean | false | Reloads all mocks on every request. Useful for developing with manual mocks. | | mocks.reqHash | function | | Callback; receives a Request object, should return a request hash | | mocks.resHash | function | | Callback; receives a HttpResponse object, Should return a response hash | | | | | | | proxy.target | string | http://localhost | The proxy target | | proxy.timeout | number | 5000 | Proxy request timeout in milliseconds |

remok.start() async

Starts the Remok server.

remok.stop() async

Stops the Remok server.

remok.use([path,] callback) 🚧

Mounts the specified middleware for the specified path.

| Property | Type | Description | | ----------------- | --------- | --------------------------------- | | path | string | Route path. | | callback | mixed | Callback; can be: A middleware function. A class with a invoke() method. |

remok.useProxy([path,] callback) 🚧

Mounts the specified proxy middleware for the specified path.

| Property | Type | Description | | ----------------- | --------- | --------------------------------- | | path | string | Route path. | | callback | mixed | Callback; can be: A middleware function. A class with a invoke() method. |

FAQ

Why does Remok create a new mock on every request, even if the request is always the same?

In order to detect new requests, Remok calculates hashes based on the request and response data.

Please make sure to exclude request and response headers that change on every request.

In this example, body and headers are not used for calculating the hash:

// Calculates a SHA256 hash. You can use any other hash function.
const hash = require('remok/dist/hash');

remok({
  mocks: {
    requestHash: (Request) => hash(Request.method + Request.url),
  },
})

How can I handle different data on subsequent requests?

🚧

I have multiple test scenarios with endpoints responding with distinct data. How can I setup those scenarios?

You can setup scenarios by running Remok with a scenario-specific mock path:

// Scenario A
remok({
  mocks: {
    path: './mocks/scenario-a',
  }
});
// Scenario B
remok({
  mocks: {
    path: './mocks/scenario-b',
  }
});

Planned features

• Middlewares
• History mode
• Record proxy response time

License

Remok is licensed under the MIT License - see the LICENSE file for details.