Mountebank: Over-the-Wire Test Doubles

Common errors

• Error: listen EADDRINUSE :::2525

  cause Mountebank's administration port (2525) or an imposter's port is already in use by another application.
  fix Change the conflicting port in your Mountebank configuration, or stop the other application using that port. For imposters, specify a different `port` in your imposter configuration. For the admin API, use `mb --port <newPort>`.

• invalid injection

  cause You are attempting to use JavaScript injection in an imposter (e.g., in a response `inject` block or predicate `inject`) without enabling the feature.
  fix Restart Mountebank with the `--allowInjection` command-line flag: `mb --allowInjection`.

• npm ERR! cb() never called!

  cause Older versions of npm (v2) can have issues with `npm shrinkwrap` or `npm install` when `mountebank` (or `@mbtest/mountebank`) is a dependency, particularly due to deep dependency trees.
  fix Upgrade npm to version 3 or higher (`npm install -g npm@latest`). If stuck on npm v2, a workaround involves adding mountebank's top-level dependencies to your `package.json` and deleting `node_modules/mountebank/node_modules` between `npm install` and `npm shrinkwrap`.

Warnings

• breaking The official npm package name changed from `mountebank` to `@mbtest/mountebank` starting from version v2.9.2. Existing projects must update their `package.json` and installation commands (`npm install -g @mbtest/mountebank`).
  Fix: Update your `package.json` dependency to `"@mbtest/mountebank": "^2.9.x"` and reinstall. For global installs, use `npm install -g @mbtest/mountebank`.
• breaking Minimum Node.js version updated to 20 for core maintenance LTS in v2.9.4. Docker images now use Node 24 (active LTS). Running on older Node.js versions may lead to instability or failures.
  Fix: Upgrade your Node.js environment to version 20 or higher. For Docker deployments, use images based on Node 24 or later.
• gotcha Using JavaScript injection (e.g., for dynamic responses or predicates) requires starting the Mountebank server with the `--allowInjection` flag. Without this flag, any imposter configuration using injection will fail with an 'invalid injection' error.
  Fix: When starting Mountebank, either via CLI or programmatically, ensure the `--allowInjection` flag is included: `mb --allowInjection` or `mb.create({ allowInjection: true })` if using a client library.
• gotcha Mountebank is not persistent by default. All configured imposters and recorded requests are lost when the server restarts unless you explicitly save and reload them using configuration files or the `--datadir` / `--impostersRepository` options.
  Fix: To persist configurations, use `mb --configfile your-imposters.json` on startup, or `mb --datadir /path/to/data` to persist all changes automatically to disk. Programmatically, ensure imposters are recreated after a server restart.

Install

• npm install mountebank npm
• yarn add mountebank yarn
• pnpm add mountebank pnpm

Imports

• mb
  wrong:

  npm install -g mountebank

  correct:

  npm install -g @mbtest/mountebank && mb

  The primary way to use Mountebank is via its command-line interface. The package name changed to `@mbtest/mountebank` in v2.9.2. Global installation makes the `mb` command available.
• mb.create
  wrong:

  const mb = require('mountebank');

  correct:

  const mb = require('@mbtest/mountebank'); const server = await mb.create({ port: 2525 });

  For programmatic control of the Mountebank server itself (e.g., starting/stopping), you can `require` the package. Ensure you use the new scoped package name `@mbtest/mountebank`.
• Imposter API

  fetch('http://localhost:2525/imposters', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(imposterConfig) })

  Programmatic creation and management of imposters (mock services) is typically done by sending HTTP requests to Mountebank's administration API, usually on port 2525 by default. No direct `import` for this, but standard HTTP client libraries are used.

Quickstart

This quickstart demonstrates how to install Mountebank globally, start the `mb` server, programmatically create a simple HTTP GET imposter via its REST API, and then verify the mock response.

import { strict as assert } from 'assert';
import { exec } from 'child_process';
import util from 'util';

const execPromise = util.promisify(exec);

const imposterConfig = {
  port: 4545,
  protocol: 'http',
  stubs: [
    {
      predicates: [{
        equals: { path: '/test', method: 'GET' }
      }],
      responses: [
        { is: { statusCode: 200, headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ message: 'Hello from Mountebank!' }) } }
      ]
    }
  ]
};

async function runMountebankQuickstart() {
  let mbProcess;
  try {
    console.log('1. Installing @mbtest/mountebank globally...');
    await execPromise('npm install -g @mbtest/mountebank');
    console.log('   Installed successfully.');

    console.log('2. Starting Mountebank server...');
    // Using `exec` to start mb in the background, ensure --allowInjection for future use cases
    // and --loglevel debug for better visibility.
    mbProcess = exec('mb --allowInjection --loglevel debug');
    mbProcess.stdout.pipe(process.stdout);
    mbProcess.stderr.pipe(process.stderr);

    // Give Mountebank a moment to start up
    await new Promise(resolve => setTimeout(resolve, 3000)); 
    console.log('   Mountebank server started (admin UI at http://localhost:2525).');

    console.log('3. Creating an HTTP imposter...');
    await fetch('http://localhost:2525/imposters', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(imposterConfig)
    });
    console.log('   Imposter created on port 4545.');

    console.log('4. Testing the mocked service...');
    const response = await fetch('http://localhost:4545/test');
    const data = await response.json();

    assert.equal(response.status, 200, 'Expected status code 200');
    assert.deepEqual(data, { message: 'Hello from Mountebank!' }, 'Expected specific mock response');
    console.log('   Mocked service responded correctly:', data);

  } catch (error) {
    console.error('An error occurred:', error.message);
    process.exit(1);
  } finally {
    if (mbProcess) {
      console.log('5. Stopping Mountebank server...');
      // Terminate the mountebank process gracefully
      await execPromise('mb stop');
      console.log('   Mountebank server stopped.');
    }
  }
}

runMountebankQuickstart();