Simulate your API locally using a Git-backed mock server

With Native Git, you can create a local mock server that’s stored in your local Git repository. A local mock server allows you to simulate a real API server locally in a branch, where you’re making API changes. This is useful for local API development and testing before committing your changes to the Postman cloud.

You can create a local mock server from a template that you can customize or using Agent Mode. You can start the mock server to simulate API responses based on the request and response logic defined in your implementation file, and view logs for APIs the mock server handles.

Before you get started, connect your Git project to your workspace.

Create a local mock server

1. Click the Items tab in the sidebar.

2. Click .

3. Select Mock and choose how you’d like to create your local mock server:

   • Create with template - Create a mock server from a template with a basic HTTP server you can customize.
   • Create with AI - Use Agent Mode to quickly create a mock server based on endpoints in the connected Git repository.

This adds two files to the postman directory in your local Git repository:

• postman/mocks/mock-server-name.js - A JavaScript file that contains the mock server implementation. Set the request and response for simulating real API behavior.
• postman/mocks/mock-server-name.json - A JSON file that contains the mock server configuration, such as the port number and routes.

Customize local mock server implementation

Set the request and response for your mock server in the mock-server-name.js implementation file to simulate behavior of a real API.

To set the request and response for your mock server, do the following:

1. Click the Items tab in the sidebar.

2. Click Local mocks.

3. Select the local mock server you want to customize.

4. Replace the placeholder values with the IDs for the request and example you want the mock server to respond with. You can click the placeholder values to view a dropdown list of request and examples to choose from.

   1
   const http = require("http");
   2
   3
   const server = http.createServer((req, res) => {
   4
   if (pm.mock.matchRequest('request-id', req)) {
   5
       return pm.mock.sendExample('example-id', res);
   6
   }
   7
   8
   ...

• You can define custom request handlers using standard HTTP server patterns. You can use conditionals, generate random values, and implement any valid JavaScript logic.
• (Recommended) You can use the pm.mock object to serve responses from your existing saved Postman examples. To learn more, see Reference requests and examples in local mock servers.

Configure local mock server details

Configure the mock server details in the mock-server-name.json file, such as the port number and routes.

To configure your mock server details, do the following:

1. Click the Items tab in the sidebar.

2. Select the local mock server you want to configure.

3. Click Edit mock configuration in the upper right to open the JSON file.

4. You can update the following details:

   • version - The version of the mock server configuration file.
   • name - The name of the mock server.
   • protocol - The protocol the mock server uses, either http or https.
   • port - The port number the mock server listens on.
   • mockSrc - The path to the JavaScript implementation file.
   • routes - An array of route objects that define the endpoints for the mock server.
   • autoRestartOnChange - A Boolean value that determines whether the mock server should automatically restart when changes are made to the configuration or implementation files.
   • logging - An object that contains logging configuration for the mock server, such as the log level and Boolean whether to show the body of requests and responses in the logs.

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 mock’s 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 local mock servers.

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.

Start a local mock server

1. Click the Items tab in the sidebar.
2. Select the local mock server you want to start.
3. Click Start in the upper right. You can also select More actions > Start next to a local mock server in the sidebar.
4. Click Copy URL to copy the URL for the mock server.
5. Click Collections in the sidebar and create an HTTP request.
6. Paste the mock server URL and send the request to see the response, simulating a real API.

Click Stop in the upper right to stop the mock server.

View mock server logs

View details about incoming requests to your local mock server and the responses sent in the logs.

1. Click the Items tab in the sidebar.
2. Select the local mock server you started.
3. View the logs on the right in the Mock Logs pane.

You can click a request to view more details about the request and response, such as the headers and body.

Click Clear logs to clear the logs for the mock server.