> 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

> For clean Markdown content of this page, append .md to this URL. For the complete documentation index, see https://learning.postman.com/llms.txt.

# Customize a mock's responses with JavaScript and pm methods

> Edit a mock's JavaScript request handlers and use pm objects like pm.mock, pm.state, and pm.datasets to return dynamic, stateful responses.

Customize a [mock](/docs/design-apis/mock-apis/mocks/overview) 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 \[#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](/docs/design-apis/mock-apis/mocks/scenarios-and-behaviors#manage-scenarios-in-a-mock) 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 icon](https://assets.postman.com/postman-docs/aether-icons/v12/descriptive-items-stroke.svg#icon) **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:

   ```js
   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 ![Package icon](https://assets.postman.com/postman-docs/aether-icons/v12/icon-entity-package-stroke.svg#icon) **Packages** to add packages to your mock. To learn more, see [Import packages into Postman](/docs/tests-and-scripts/write-scripts/packages/overview).

If you [deployed your mock as a mock server](/docs/design-apis/mock-apis/mock-servers/from-a-mock), 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](#use-pm-methods-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`](/docs/postman-cli/postman-cli-mock#postman-mock-run).

### Push and pull mocks \[#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](/docs/use/native-git/sync/). From the Postman CLI, you can also use [`postman mock push`](/docs/postman-cli/postman-cli-mock#postman-mock-push) to upload a mock to the Postman Cloud.

## Use pm methods in the mock editor \[#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](/docs/tests-and-scripts/write-scripts/postman-sandbox-reference/overview/).

### pm.mock \[#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](/docs/tests-and-scripts/write-scripts/postman-sandbox-reference/pm-mock/).

### pm.state \[#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](/docs/design-apis/mock-apis/mock-servers/from-a-mock), 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](/docs/tests-and-scripts/write-scripts/postman-sandbox-reference/pm-state/).

You can also [inspect state for your mock](/docs/design-apis/mock-apis/mocks/run-a-mock#inspect-a-running-mock).

### pm.datasets \[#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](/docs/tests-and-scripts/write-scripts/postman-sandbox-reference/pm-datasets/).

### pm.test and pm.expect \[#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](/docs/tests-and-scripts/write-scripts/postman-sandbox-reference/pm-test-expect).

### pm.environment \[#pm-environment]

The `pm.environment` object provides access to variables in the active environment. To learn more, see [Reference variables in Postman scripts](/docs/tests-and-scripts/write-scripts/postman-sandbox-reference/pm-variables#pmenvironment).

### pm.globals \[#pm-globals]

The `pm.globals` object provides access to global variables at the workspace level. To learn more, see [Reference variables in Postman scripts](/docs/tests-and-scripts/write-scripts/postman-sandbox-reference/pm-variables#pmglobals).