Mock server commands

This topic covers mock server commands for the Postman CLI.

`postman mock run`

You can use the postman mock run command to start a mock, which is a code-based JavaScript API simulator, from a configuration file. The command isn’t supported for mocks deployed to the Postman cloud.

To run a collection against a mock, use the --mock option with the postman collection run command.

This command starts a mock from a configuration file in JSON format. With the configuration file, you can configure details like the mock’s port number, name, script, and more. The mock runs on the specified port until you stop it. If the specified port is already in use, the mock falls back to an available port assigned by the OS. Make sure you also have a JavaScript file with an HTTP server that sets the request and example response for simulating real API behavior.

Add the command to your CI/CD script to start a mock as a dependency for your application or test suite. Once running, your service or external tests can send requests to it as if it were a real API. This enables you to simulate API behavior for testing and development.

Learn more at Build API mocks with JavaScript.

Usage

$ postman mock run <config-file>

<config-file>

The path to the mock server configuration file in JSON format.

Options

-e, --environment <path>

Specifies the path to an environment file (JSON or YAML) loaded into pm.environment for the mock server’s scripts.

-g, --globals <path>

Specifies the path to a globals file (JSON or YAML) loaded into pm.globals for the mock server’s scripts.

-p, --port <port>

The port the mock server listens on. Pass auto for an OS-assigned ephemeral port. By default, the mock uses the port from its configuration, falling back to an ephemeral port if that port is busy.

Example

$ postman mock run mock-config.json
$ 
$ postman mock run mock-config.json --environment ./postman/environments/dev.yaml

`postman mock generate`

You can use the postman mock generate command to generate a runnable mock from a Postman Collection or an OpenAPI 3.0 or 3.1 specification. The command auto-detects the source type. It accepts a collection in v2.0, v2.1, or v3 format, either as a file or a Git-native v3 collection directory, or an OpenAPI specification file.

If you run the command without a source, it generates a sample mock with a GET /health endpoint that you can use as a starting point.

After you generate a mock, start it with the postman mock run command.

Learn more at Build API mocks with JavaScript.

Usage

$ postman mock generate [source-path] [options]

[source-path]

The path to the source collection or OpenAPI specification file. The source type is auto-detected. If omitted, the command generates a sample mock.

Options

-o, --output <dir>

Defaults to postman/mocks/<slug>

The output directory for the generated mock. You can’t use this option with --update.

--name <name>

A display name for the generated mock.

--port <port>

Defaults to 4500

The port the mock server listens on.

--force

Overwrites the config.yaml or default.js file in the output directory if it already exists.

-u, --update <mock-path>

Updates an existing mock in place from the source. Provide the path to its config.yaml file, or the directory that contains it. This regenerates the default scenario handler and preserves the existing name, port, and scenarios. You can’t use this option with --output.

-x, --suppress-exit-code

Always exits with code 0, even on failure.

Examples

$ postman mock generate ./my-collection.json
$ 
$ postman mock generate ./openapi.yaml \
>   --output ./postman/mocks/api \
>   --port 4010
$ 
$ postman mock generate ./my-collection.json \
>   --update ./postman/mocks/orders

`postman mock get`

Use the postman mock get command to show the details and run status of a mock.

Usage

$ postman mock get <path-or-directory>

<path-or-directory>

The path to a mock, or a directory that contains one.

Options

--json

Outputs the mock details in JSON format instead of a table.

Examples

$ postman mock get ./postman/mocks/orders
$ 
$ postman mock get ./postman/mocks/orders --json

`postman mock list`

Use the postman mock list command to list the mocks found under a directory.

Usage

$ postman mock list [path-or-directory]

[path-or-directory]

The directory to search for mocks. If omitted, the command searches the current directory.

Options

--json

Outputs the mock list in JSON format instead of a table.

Examples

$ postman mock list
$ 
$ postman mock list ./postman/mocks
$ 
$ postman mock list ./postman/mocks --json

`postman mock delete`

Use the postman mock delete command to permanently remove a mock artifact.

Usage

$ postman mock delete <path-or-directory>

<path-or-directory>

The path to the mock to delete, or a directory that contains one.

Options

-y, --yes

Skips the confirmation prompt.

Examples

$ postman mock delete ./postman/mocks/orders
$ 
$ postman mock delete ./postman/mocks/orders --yes