Stub matching, response shaping, and stateful scenarios

Stub matching

The stubFor DSL composes a request-matcher chain:

Stubs are first-match-wins by default; the most specific stub should be registered first.

Response shaping

stubFor(get("/orders/42")
    .willReturn(aResponse()
        .withStatus(200)
        .withHeader("Content-Type", "application/json")
        .withBody("{\"order_id\": 42}")
        .withFixedDelay(500)               // simulate latency
        // OR
        .withChunkedDribbleDelay(5, 1000)  // simulate slow chunked transfer
    ));

Common helper response builders:

Stateful stubs (scenarios)

For workflows that depend on prior state (e.g. "first call returns empty cart, second call returns populated cart"):

stubFor(get("/cart")
    .inScenario("Add to cart")
    .whenScenarioStateIs(STARTED)
    .willReturn(okJson("[]")));

stubFor(post("/cart/add")
    .inScenario("Add to cart")
    .whenScenarioStateIs(STARTED)
    .willSetStateTo("Added")
    .willReturn(ok()));

stubFor(get("/cart")
    .inScenario("Add to cart")
    .whenScenarioStateIs("Added")
    .willReturn(okJson("[{\"sku\":\"SKU-1\"}]")));

Mountebank - multi-protocol mock servers

Reference detail for wiremock-stubs (opens in new window). WireMock and MSW are HTTP-only; Mountebank covers the multi-protocol long tail. Author imposters (mock servers) by POSTing JSON definitions to the control API on port 2525.

Per mountebank-readme (opens in new window), supported protocols include: HTTP / HTTPS, TCP (text and binary), SMTP, LDAP, gRPC, WebSockets, GraphQL, SNMP, Telnet / SSH, and NETCONF.

Docs-domain note (verified 2026-05-04): the canonical mbtest.org domain was hijacked (redirects to an unrelated site), so this reference cites the GitHub repo bbyars/mountebank (opens in new window); 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).
• 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 (the parent skill) 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 (opens in new window).)

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

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

Set up an imposter as a proxy to a real upstream:

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

proxyOnce is the canonical record-playback workflow - run tests once against a real upstream to populate the imposter, then run forever offline. Each distinct request hits the upstream and Mountebank stores the response as a stub; on every later run the stored stubs answer and the real API is never called.

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.

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 at the top: cite the GitHub README and mbtest.dev.

References

• mountebank-readme (opens in new window) - main repo: install, supported protocols, key features.
• mbtest.dev - alternate documentation domain (verify before linking).
• msw-handlers - HTTP-only alternative for browser + Node.