Configuring mountebank

start is the default mb command, meaning:

mb start [options]

is identical to

mb [options]

Running mb by itself, without any options, will start up the API on port 2525. It will also spin up this website on http://localhost:2525/, giving you accurate documentation for the version of mountebank you're running, as the official site only contains the latest docs. The following options are available:

{
  "level": "info",
  "transports": {
    "console": {
      "colorize": true,
      "format": "%level: %message"
    },
    "file": {
      "path": "mb.log",
      "format": "json"
    }
  }
}

mb --port 3000 --allowInjection --origin 'http://first.com' --origin 'http://second.com' \
--log '{ "level": "warn", "transports": { "console": { "format": "json" } } }'

mb start --rcfile .mbrc

{
  "port": 3000,
  "allowInjection": true,
  "origin": ["http://first.com", "http://second.com"],
  "log": {
    "level": "warn",
    "transports": {
      "console": {
        "format": "json"
      }
    }
  }
}

mb stop [options]

Stops mb, shutting down all open sockets. Generally, mb stop must be run from the same directory as the mb start command, although that is configurable with the pidfile option:

mb restart [options]

The restart command is equivalent to running mb stop followed by mb start. To ensure a clean stop, the --pidfile must match the one passed to the original mb start process. By default, this means you must run restart in the same working directory you originally ran the start command from.

The restart command has all the same command line options as the start command.

mb save [options]

While you can always use the API to capture the current configuration of imposters, mountebank provides a convenient command line mechanism to save the configuration into a file that can be used to start a subsequent process of mb using the --configfile command line option. With a running mb process operating on port 3000, you can execute the following command:

mb save --port 3000 --savefile saved.json --removeProxies

All of the parameters are optional with the defaults listed in the table below. You could then restart mountebank with the following command:

mb restart --port 3000 --configfile saved.json

The save command takes the following options:

mb replay [options]

The replay command is a convenience that removes all proxies, effectively switching from record mode to replay mode. Assuming mountebank is running on port 3000, you would run the following command:

mb replay --port 3000

That will reset the imposter configuration by sending a PUT command to /imposters based on the current configuration, excluding the proxies (using the ?removeProxies=true query parameter). The following options are available:

mb help

Lists basic command line help. You can get more detailed help for a command with the following:

mb command --help

The default formatter for mountebank allows you to use EJS (version 2.x) templates to split the test data into multiple files. This is particularly useful for separating out JavaScript injection functions and XML or JSON HTTP response bodies because you store them as multi-line files and rely on templating to turn them into JSON-friendly single line strings. It remains the default for backwards compatibility, even though EJS 3.x has made breaking changes.

mountebank will pass a stringify function into your templates that allows you to put multi-line strings in separate files. The example below is loosely based on the response injection example described on the Injection page, and shows the use of the stringify function. The path passed in to stringify is relative to the root file referenced in the configfile command line parameter. You can also pass a custom object, referenced as data in child templates, as the second parameter of stringify. This is useful if you want to reuse the same template but add some dynamic data. For an example, look at the stringify call in templates/originServer.ejs below, and using the custom field in templates/originXMLResponse.ejs.

Assuming the files below are in a relative directory called templates, you can initialize mb with the following command:

mb --configfile templates/imposters.ejs --allowInjection --localOnly

templates/imposters.ejs

{
  "imposters": [
    <% include originServer.ejs %>,
    <% include proxyServer.ejs %>
  ]
}

templates/originServer.ejs

{
  "port": 5555,
  "protocol": "http",
  "name": "origin",
  "stubs": [
    {
      "predicates": [{ "contains": { "headers": { "Content-Type": "xml" } } }],
      "responses": [{ "is": { "body": "<%- stringify('originXMLResponse.ejs', { value: 'first }) %>" }}]
    },
    {
      "responses": [{ "inject": "<%- stringify('originServerResponse.ejs') %>" }]
    }
  ]
}

templates/originXMLResponse.ejs

<rootNode>
  <childNode><%= data.value %></childNode>
</rootNode>

templates/originServerResponse.ejs

(request, state, logger) => {
    logger.info('origin called');
    state.requests = state.requests || 0;
    state.requests += 1;
    return {
      headers: {
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ count: state.requests })
    };
}

templates/proxyServer.ejs

{
  "port": 4546,
  "protocol": "http",
  "name": "proxy",
  "stubs": [
    {
      "responses": [{ "inject": "<%- stringify('counter.ejs') %>" }],
      "predicates": [{
        "equals": {
          "method": "GET",
          "path": "/counter"
        }
      }]
    },
    {
      "responses": [{ "inject": "<%- stringify('proxy.ejs') %>" }]
    }
  ]
}

templates/counter.ejs

function (request, state) {
    var count = state.requests ? Object.keys(state.requests).length : 0;

    return {
        body: `There have been ${count} proxied calls`
    };
}

templates/proxy.ejs

function (request, state, logger, callback) {
    var cacheKey = request.method + ' ' + request.path;

    if (typeof state.requests === 'undefined') {
        state.requests = {};
    }

    if (state.requests[cacheKey]) {
        logger.info('Using previous response');
        callback(state.requests[cacheKey]);
    }

    var http = require('http'),
        options = {
            method: request.method,
            hostname: 'localhost',
            port: 5555,
            path: request.path,
            headers: request.headers
        },
        httpRequest = http.request(options, response => {
            var body = '';
            response.setEncoding('utf8');
            response.on('data', chunk => {
                body += chunk;
            });
            response.on('end', () => {
                var stubResponse = {
                        statusCode: response.statusCode,
                        headers: response.headers,
                        body
                    };
                logger.info('Successfully proxied: ' + JSON.stringify(stubResponse));
                state.requests[cacheKey] = stubResponse;
                callback(stubResponse);
            });
        });
    httpRequest.end();
}

A formatter is a CommonJS module that exports two functions: load, used to load the configuration when the configfile option is passed to mb start, and save, used to save the configuration for mb save. The formatter gives you total control over how the test data is stored, allowing you to improve readability (which suffers by default from JSON's single line requirement for strings) or to convert between formats of other service virtualization tools.

The default formatter that ships with mountebank is described above ("Default config file parsing"). The example below shows a simple (and silly) formatter that encodes all data as Base64.

'use strict';

function encode (obj) {
    return Buffer.from(JSON.stringify(obj)).toString('base64');
}

function decode (text) {
    return Buffer.from(text, 'base64').toString('utf8');
}

function load (options) {
    const fs = require('fs'),
        contents = fs.readFileSync(options.configfile, { encoding: 'utf8' });
    return JSON.parse(decode(contents));
}

function save (options, imposters) {
    const fs = require('fs');

    if (options.customName && imposters.imposters.length > 0) {
        imposters.imposters[0].name = options.customName;
    }
    fs.writeFileSync(options.savefile, encode(imposters));
}

module.exports = { load, save };

All CLI options are passed to both the load and save functions, allowing you to define custom options specific to your formatter. You can see an example of this in the save function, which takes a customName option and makes it the saved name of the first imposter.

The code above shows a synchronous implementation, but mountebank will accept a promise return value.

Assuming the module is saved as 'customFormatter.js', the following commands will use it for saving and loading:

mb save --savefile mb.json --formatter customFormatter
mb restart --configfile mb.json --formatter customFormatter