mountebank-imposters

Overview

Mountebank is a multi-protocol service-virtualization (mock server) tool: stand up on-demand mocks across many protocols by POSTing JSON imposter definitions to its control API on port 2525, so tests run against deterministic stubs instead of live dependencies.

Per mountebank-readme, supported protocols include:

• HTTP / HTTPS
• TCP (text and binary)
• SMTP
• LDAP
• gRPC
• WebSockets
• GraphQL
• SNMP
• Telnet / SSH
• NETCONF

Docs-domain note (verified 2026-05-04): the canonical mbtest.org domain was hijacked (redirects to an unrelated site), so this skill cites the GitHub repo bbyars/mountebank; mbtest.dev is the project's alternate docs domain. Verify both URLs before linking from authored content.

When to use

• The project mocks non-HTTP protocols (TCP, SMTP, LDAP, gRPC). WireMock and MSW are HTTP-only; Mountebank covers the long tail.
• The team wants record-playback proxying - Mountebank can proxy to a real upstream during recording, then replay the captured responses in subsequent test runs.
• The team needs JavaScript injection for dynamic response computation per request.

If the team is HTTP-only on the JVM, wiremock-stubs is the lighter fit. For Node / browser HTTP-only, use msw-handlers. Mountebank's strength is multi-protocol breadth; pay the operational cost (a separate process, port 2525) only when you need it.

How to use

1. Start Mountebank (mb start or the Docker image); the control API listens on port 2525.
2. POST a JSON imposter to /imposters with a port, a protocol, and one or more stubs.
3. Give each stub predicates (path / method / header / body matchers) and responses (the reply to send).
4. Verify: GET http://localhost:2525/imposters/<port> and assert HTTP 200 with your stubs listed before pointing tests at it. If it 404s or the stub is missing, the POST body was malformed - fix the JSON and re-POST.
5. Point the system under test at the imposter's port and run the tests.
6. For an unrecorded upstream, use a proxyOnce proxy response to capture real traffic, then replay offline.
7. DELETE /imposters/<port> in teardown (or restart Mountebank) so stale stubs don't leak between runs.

Install

npm install -g @mbtest/mountebank

(Per mountebank-readme.)

For Docker-based CI (preferred for runner cleanliness):

docker run --rm -p 2525:2525 -p 4545:4545 bbyars/mountebank:latest start

The control API listens on port 2525; imposter ports (4545 in the example) are configured per imposter.

Authoring imposters

Mountebank's data model uses these layers:

Create an HTTP imposter

POST to the control API:

curl -X POST http://localhost:2525/imposters \
  -H 'Content-Type: application/json' \
  -d '{
    "port": 4545,
    "protocol": "http",
    "stubs": [{
      "predicates": [{
        "and": [
          { "equals": { "method": "GET", "path": "/orders/42" } }
        ]
      }],
      "responses": [{
        "is": {
          "statusCode": 200,
          "headers": { "Content-Type": "application/json" },
          "body": "{\"order_id\": 42, \"status\": \"shipped\"}"
        }
      }]
    }]
  }'

After this POST, GET http://localhost:4545/orders/42 returns the stubbed response.

Predicate operators

Beyond equals, Mountebank offers deepEquals, contains, startsWith / endsWith, matches (regex), exists, the boolean not / or / and, and inject for a custom JavaScript predicate. Full operator table: references/predicates-and-proxying.md.

Multi-stub responses (cycle through)

If a stub has multiple responses, Mountebank cycles through them in order on subsequent matching requests:

{
  "stubs": [{
    "predicates": [{ "equals": { "method": "GET", "path": "/poll" } }],
    "responses": [
      { "is": { "statusCode": 202 } },
      { "is": { "statusCode": 202 } },
      { "is": { "statusCode": 200, "body": "DONE" } }
    ]
  }]
}

Three calls: 202, 202, 200, then it cycles back. Useful for modeling polling endpoints.

Proxying for record-playback

Point an imposter's response at a real upstream with a proxy block. proxyOnce records the first response as a stub then replays it, proxyAlways records every call, and proxyTransparent passes through without recording. The record-playback config and the full mode table are in references/predicates-and-proxying.md.

Test framework integration

For Node.js test suites, use the mountebank npm package programmatically:

import mb from 'mountebank';

const mbServer = await mb.create({ port: 2525, allowInjection: true });

// POST imposter via fetch / axios / the mb client lib
await fetch('http://localhost:2525/imposters', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ port: 4545, protocol: 'http', stubs: [...] }),
});

// Run tests against http://localhost:4545

// Tear down
await fetch('http://localhost:2525/imposters/4545', { method: 'DELETE' });
await mbServer.close();

CI integration

# .github/workflows/integration.yml
- name: Start Mountebank
  run: |
    npx -p @mbtest/mountebank mb start &
    npx wait-on http://localhost:2525

- name: Seed imposters
  run: bash scripts/seed-mountebank.sh

- run: npm test

- name: Stop Mountebank
  if: always()
  run: pkill -f 'mountebank' || true

For a more robust pattern, run Mountebank in Docker as a sidecar service rather than a background process - kills + cleanup are cleaner.

Worked example

A test suite depends on a flaky third-party payments API. Record it once, then run offline. Create a proxy imposter that forwards every path to the real upstream in proxyOnce mode:

{
  "port": 4545,
  "protocol": "http",
  "stubs": [{
    "predicates": [{ "matches": { "path": ".*" } }],
    "responses": [{ "proxy": {
      "to": "https://payments.example.com",
      "mode": "proxyOnce"
    }}]
  }]
}

Run the suite once with the real upstream reachable: each distinct request hits payments.example.com and Mountebank stores the response as a stub. On every later run the stored stubs answer and the real API is never called - the suite is deterministic and offline.

Anti-patterns

Limitations

• Operational overhead. A separate process / container per CI run; harder to set up than in-process WireMock or MSW.
• JSON-heavy authoring. Imposter definitions are JSON-by-API; there's no fluent DSL like WireMock's stubFor.
• Documentation domain reliability. See the docs-domain note in the Overview: cite the GitHub README and mbtest.dev.

References

• mountebank-readme - main repo: install, supported protocols, key features.
• mbtest.dev - alternate documentation domain (verify before linking).
• wiremock-stubs - HTTP-only alternative on the JVM.
• msw-handlers - HTTP-only alternative for browser + Node.