Skip to content

Mountebank Compatibility

Rift implements the Mountebank REST API and configuration format, so most Mountebank configurations and clients work with Rift unchanged. Where Rift behaves differently, the difference is listed in Differences from Mountebank.

Version: Rift is compatible with Mountebank 2.9.5, the latest release. Mountebank now publishes as @mbtest/mountebank; the old mountebank npm package stops at 2.9.1. Every pull request that changes the engine replays the differential corpus against Mountebank 2.9.5 and Rift, and a weekly job opens an issue when a newer Mountebank is released. The deliberate exceptions are listed in Differences from Mountebank.

Scope: Rift imposters are HTTP/HTTPS only. Mountebank also supports tcp and smtp imposters, which Rift rejects — see the migration guide for the full compatibility table before you migrate. (This is separate from TCP fault injection, which HTTP imposters do support.)

New to the model? Start with Concepts — it explains imposters, stubs, predicates, responses, and behaviors conceptually, then the Rift-specific stateful features. This section is the syntax-level reference for the Mountebank-compatible surface.

Core Concepts

Imposters

An imposter is a mock server listening on a specific port. Each imposter:

  • Listens on a configurable port
  • Handles HTTP or HTTPS protocol
  • Contains one or more stubs for request matching

Stubs

A stub defines how to respond to matching requests:

  • Predicates: Rules to match incoming requests
  • Responses: What to return when predicates match

Predicates

Predicates define request matching criteria:

  • equals, deepEquals - Exact match
  • contains, startsWith, endsWith - Partial match
  • matches - Regex match
  • exists - Field existence check
  • inject - JavaScript function (requires --allowInjection)
  • jsonpath, xpath - Selectors that scope any of the above to part of a JSON or XML body
  • and, or, not - Logical combinations

Behaviors

Behaviors modify responses before sending:

  • wait - Add latency
  • repeat - Serve a response several times before moving to the next
  • copy - Copy request values to response
  • lookup - Look up a row in a CSV file
  • decorate - Transform response with JavaScript
  • shellTransform - Pipe the response through a shell command

Quick Example

Create an imposter with multiple stubs:

{
  "port": 4545,
  "protocol": "http",
  "name": "User Service Mock",
  "stubs": [
    {
      "predicates": [{
        "equals": { "method": "GET", "path": "/health" }
      }],
      "responses": [{
        "is": { "statusCode": 200, "body": "OK" }
      }]
    },
    {
      "predicates": [{
        "and": [
          { "equals": { "method": "GET" } },
          { "matches": { "path": "/users/\\d+" } }
        ]
      }],
      "responses": [{
        "is": {
          "statusCode": 200,
          "headers": { "Content-Type": "application/json" },
          "body": { "id": 1, "name": "User" }
        }
      }]
    },
    {
      "predicates": [{
        "equals": { "method": "POST", "path": "/users" }
      }],
      "responses": [{
        "is": {
          "statusCode": 201,
          "headers": { "Content-Type": "application/json" },
          "body": { "id": 999, "message": "Created" }
        },
        "_behaviors": {
          "wait": 100
        }
      }]
    }
  ]
}

REST API

Create Imposter

POST /imposters
Content-Type: application/json

{
  "port": 4545,
  "protocol": "http",
  "stubs": [...]
}

List Imposters

GET /imposters

Get Imposter

GET /imposters/{port}

Delete Imposter

DELETE /imposters/{port}

Delete All Imposters

DELETE /imposters

Documentation Sections