Customize a mock's responses with JavaScript and pm methods

This page is for Postman Docs, version Latest (v12) (default). For other versions, use one of these documentation indexes: - Latest (v12) (default): https://learning.postman.com/latest-v-12/llms.txt - v11: https://learning.postman.com/v11/llms.txt

Customize a mock to define how it handles requests and returns responses. Edit the mock’s JavaScript implementation directly, and use pm objects to serve saved examples, persist state across requests, and return data from datasets.

Customize your mock

In Local View, define how your mock handles requests and returns responses. This is where you reproduce the behavior of a real API. The implementation is stored in the <scenario-name>.js file. Each scenario has its own implementation, so you can customize how each one handles requests independently.

To customize your mock, do the following:

1. Click the Items tab in the sidebar.

2. Click Mocks.

3. Select a mock you want to customize.

4. In the Code pane, update the implementation with your request handling logic.

   Example:

   const http = require("http");
   const server = http.createServer((req, res) => {
       if (pm.mock.matchRequest('<request-path>', req)) {
           return pm.mock.sendExample('<example-path>', res);
       }
   ...
   });

Mocks are implemented using custom request handlers. You can use standard HTTP server patterns to control how requests are handled. For example, you can add conditionals, generate dynamic data, or implement any valid JavaScript logic.

Packages from the Postman Package Library and external registries are supported in mock implementation files. Click Packages to add packages to your mock. To learn more, see Import packages into Postman.

If you deployed your mock as a mock server, you can click Mock Server in the upper right to view it.

Within these handlers, you can:

• Use pm.mock to serve responses from your saved examples.
• Use pm.state to persist data across requests and enable stateful behavior.
• Use pm.datasets to query datasets and use the data in your request handling logic.
• Use pm.test and pm.expect to add test assertions and validate request or response data.

Learn more about the pm objects available in the mock editor.

You can also edit the handler .js files directly in your code editor and run the mock from the Postman CLI with postman mock run.

Push and pull mocks

You can push and pull mocks to and from the Postman Cloud. You can push mocks to the Postman Cloud to share them with your team. You can also pull mocks from the Postman Cloud to your local workspace to start it locally.

Learn more about syncing local and cloud elements with Native Git. From the Postman CLI, you can also use postman mock push to upload a mock to the Postman Cloud.

Use pm methods in the mock editor

You can use some pm objects in the mock editor the same way you use them in scripts.

pm.mock

Postman provides an object called pm.mock that’s available in the mocks sandbox environment. It gives you structured, Postman-aware functions for matching incoming requests and sending responses. This includes the ability to serve responses from your existing saved Postman examples rather than hard-coding everything. To learn more, see Reference requests and examples in mocks.

pm.state

Postman provides an object called pm.state that’s available in the mocks sandbox environment. It provides a persistent store for managing data across requests, enabling your mock to behave like a real service instead of returning static responses. State persists across runs until it’s cleared using pm.state.clear().

By default, all requests to a local mock share a single state store. When you deploy the mock as a mock server, sessions are turned on by default, so each caller gets an isolated copy of state identified by the x-mock-session header. To learn more, see Persist state across requests in mocks.

You can also inspect state for your mock.

pm.datasets

Postman provides a function called pm.datasets that enables you to access datasets and run SQL queries against them. You can run predefined views or custom queries to retrieve structured data at runtime. This enables you to use persistent, queryable data across requests, making your mocks more dynamic and realistic. To learn more, see Manage and use datasets in scripts.

pm.test and pm.expect

The pm.test object enables you to define test assertions in your mock implementation file. You can use it with pm.expect, which provides Chai-style expectations for validating request headers, body content, status codes, or custom variables. Test results (pass, fail, or skip) are recorded and surfaced in mock logs. Learn more about writing tests using pm.test and pm.expect.

pm.environment

The pm.environment object provides access to variables in the active environment. To learn more, see Reference variables in Postman scripts.

pm.globals

The pm.globals object provides access to global variables at the workspace level. To learn more, see Reference variables in Postman scripts.