mountebank Documentation

mountebank provides service virtualization for a wide range of protocols, either natively or through community extensions. Supported protocols include:

• http
• https
• tcp (text and binary)
• smtp
• ldap
• grpc
• websockets
• graphql
• snmp
• telnet
• ssh
• netconf

mountebank is a service virtualization tool that supports:

• Mock verification: Verifying that specific interactions occurred.
• Stubbing with advanced predicates: Providing canned responses based on complex matching logic.
• JavaScript injection: Allowing custom logic to be executed during the mocking process.
• Record-playback: Using a proxy to capture real traffic and replay it as stubs.

The repository contains two packages: mountebank (the core tool) and mbTest (out-of-process tests).

To build and run tests locally:

1. Install dependencies for both packages using npm install.
2. Run the test suite using npm test.

Note on DNS failures: Some tests require network access and verify behavior during DNS failures. If these tests fail due to your ISP hijacking NXDOMAIN responses, you can run them in 'airplane mode' by setting the MB_AIRPLANE_MODE environment variable to true.

To use mountebank, install it globally via npm and then execute the mb command to start the service. You can customize the service using various command line options.

npm install -g @mbtest/mountebank

mb

You can provide a JSON file via the --rcfile flag to pre-configure the server.

Precedence Rule: CLI options passed directly to the command line always take priority over settings defined in the rcfile.

Example config.json:

{
  "port": 4000,
  "loglevel": "warn",
  "allowInjection": true
}

Run it with:

mb start --rcfile config.json

The mb command-line interface allows you to manage the mountebank server lifecycle and configuration. The default command is start if no command is specified.

Available Commands

• start: Starts the mountebank server. This is the default action.
• stop: Stops the running server using the process ID stored in a PID file.
• restart: Stops the server (if running) and starts it again.
• save: Saves the current imposter configuration (including responses created by proxies) to a file.
• replay: Switches the server from record mode to replay mode by removing all proxies.

When calling create or createApp, you can pass an options object to configure the server behavior.

Key configuration properties include:

• port: The port the server will listen on (defaults to 2525).
• host: The hostname to bind to (defaults to localhost).
• ipWhitelist: An array of allowed IP addresses/ranges (defaults to ['*']).
• apikey: Used for validating API key middleware.
• origin: Configures CORS allowed origins.
• allowInjection: If set, enables injection capabilities (use with caution; see /docs/security for details).

Mountebank allows you to choose how virtual services (imposters) are stored and managed by providing specific keys in your startup configuration object.

1. Custom Repository: If config.impostersRepository is provided, Mountebank attempts to load a custom repository module from the specified file path. If the file does not exist, it falls back to the in-memory repository.
2. File System Backed: If config.datadir is provided (but no custom repository is specified), Mountebank uses a file-system-backed repository to persist imposters.
3. In-Memory (Default): If neither of the above is provided, Mountebank defaults to an in-memory repository, meaning all imposters are lost when the process restarts.

The select function allows you to extract specific values from a JSON object or a JSON string using a JSONPath selector.

• If the input possibleJSON is already an object, it is used directly.
• If the input possibleJSON is a string, the function attempts to parse it as JSON.
• If the selector matches a single string value, that string is returned.
• If the selector matches multiple values, an array of those values is returned.
• If no matches are found, or if the input is not valid JSON, the function returns undefined.

If a logger is provided, the function will log a warning if JSON parsing fails.