Simulate real-world conditions in Postman

With Postman Simulator, you can create simulations to test how your service behaves under real-world conditions by applying failure scenarios like latency, errors, and rate limits.

Simulations can be applied to code mocks, which enable you to simulate your API’s dependencies and test how your service behaves without calling real services.

Scenarios are applied dynamically as your mock server handles requests. This enables you to observe how your service responds to disruptions and performance constraints. With simulations, you can identify and fix issues before deploying to staging or production.

Create a simulation

Create a simulation to apply failure scenarios to one or more code mocks. Before you create a simulation, make sure you have at least one code mock set up. To learn how, see Simulate APIs with code mock servers.

To create a simulation, do the following:

1. Open a workspace and select Tools > Simulations in the footer.

2. Click Create simulation.

3. Enter a name for the simulation.

4. (Optional) Customize the URL for the simulation or keep the auto-generated one. The customized URL must be unique and can only have lowercase letters, numbers, and hyphens.

5. Choose how requests access mock servers in the simulation:

   • URL path — Route requests to a mock server using a unique path in the request URL. For example: https://<my-simulation>.sim.<team>.postman.dev/<mock-slug>/<endpoint>
   • Header — Route requests to a mock server using a request header while sharing the same simulation URL. For example: x-mock-slug: <mock-slug>

6. Select the code mocks you’d like to add to the simulation.

7. Click Create simulation.

Simulations show in the left sidebar under Mocks and Mock Servers. You can select a simulation to view its details, including the code mocks included in the simulation and the scenarios applied to each mock.

Once you’ve created the simulation, you can apply scenarios to the simulation to simulate specific conditions.

In Local View, a simulation file is created in your local Git repository with the configuration for the simulation. In Cloud View, the simulation configuration is synced to the Postman cloud.

About the simulation file

When you create a simulation in Local View, Postman creates a simulation file in your local Git repository with the configuration for the simulation, including the code mocks and scenarios. This file is used to start the code mocks with the selected scenarios when you start a simulation.

The simulation file is located at postman/simulations/<simulation-name>.sim.yaml. You can edit this file directly to update the code mocks and scenarios included in the simulation. You can also use Agent Mode to quickly update the simulation file.

Apply scenarios to a simulation

Apply scenarios to simulate conditions like errors, latency, and rate limits for the code mocks in a simulation. You can apply scenarios before or during a simulation to test how your API behaves under different conditions.

1. Open a workspace and select Tools > Simulations in the footer.

2. Select the simulation you’d like to apply scenarios to.

3. (Optional) Update the code mocks included in the simulation.

4. Turn on the toggle next to the scenarios you want to simulate for each code mock:

   • Simulate Error Responses — Simulate error responses by returning a specified HTTP status code.
   • Add Response Delay — Simulate network latency by adding a delay (in milliseconds) before the code mock sends a response.
   • Simulate Rate Limiting — Simulate rate limiting by specifying a maximum number of requests allowed per minute.
   • Chaos Mode — Randomly fails a percentage of requests with 5xx status codes.
   If you enable both Simulate Error Responses and Chaos Mode, and the configured error response is a 5xx status code (such as 502), Chaos Mode only returns that specific 5xx error. For example, if you select 502, Chaos Mode only returns 502 responses.

   If your goal is to test 5xx failures, use either Simulate Error Responses or Chaos Mode.

5. Start a simulation and send requests to the mock server URL.

Start a simulation

You can start all code mocks in the simulation or start them individually. You can also start a simulation using the Collection Runner or the Postman CLI. You need to start the code mock to send requests to it.

To start a simulation from Postman Simulator, do the following:

1. Open a workspace and select Tools > Simulations in the footer.

2. Select the simulation you’d like to start.

3. (Optional) Update the code mocks and scenarios in the simulation.

4. Click Start to start all code mocks in the simulation. In Local View, you can also click Start mock to start an individual code mock.

5. Send requests to the code mock URLs and observe the responses with the simulated conditions applied. For each mock, note the slug and include it in the request URL or header depending on how you set up the simulation.

   For example, if the simulation URL is https://my-simulation.sim.my-team.postman.dev and you have a mock server with the slug new-mock-049rk, you can send a request to https://my-simulation.sim.my-team.postman.dev/new-mock-049rk/items or include the header x-mock-slug: new-mock-049rk with the request.

6. View simulation logs to analyze how the simulated conditions are affecting your API’s behavior.

To start a simulation with the Collection Runner, see Run a collection with a simulation.

To start a simulation with the Postman CLI:

• Use the postman simulate run command to start a simulation. See Simulator commands for details.
• Use the --simulate option with the postman collection run command to run a collection with a simulation. See Collection commands for details.

View simulation logs

After you start a simulation, you can view the logs for the mock servers included in the simulation.

1. Open a workspace and select Tools > Simulations in the footer.
2. Select a simulation with running mock servers.
3. View the logs in the Logs pane.

You can filter logs by path, mock server, method, status code, and time range. This helps you analyze how the simulated conditions are affecting your API’s behavior. For example, you can filter by status code to see only failed requests or filter by method to see how different endpoints are affected.

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 code mock.

Edit a simulation configuration

You can edit the configuration for a simulation to update the code mocks and scenarios included in the simulation. In Local View, you can also edit the simulation file directly to update the configuration. In Cloud View, you can configure details like the URL or how requests access mock servers in the simulation.

Edit a simulation configuration in Local View

To edit a simulation configuration in Local View, do the following:

1. Open a workspace and select Tools > Simulations in the footer.

2. Select the simulation you’d like to edit.

3. Select the YAML tab to view the simulation file.

4. You can update the following details:

   • id — The unique identifier for the simulation.
   • simulation — The name of the simulation.
   • slug — The unique slug for the simulation URL.
   • routing — The routing method for requests to access code mocks in the simulation. This can be either path or header.
   • mocks — The path to the implementation files for the code mocks included in the simulation.

Edit a simulation configuration in Cloud View

To edit a simulation in Cloud View, do the following:

1. Open a workspace and select Tools > Simulations in the footer.
2. Select the simulation you’d like to edit.
3. In the upper right of the workbench, click Edit configurations.
4. You can update the URL for the simulation.
5. You can update how requests access code mocks in the simulation.
6. Click Confirm.

Update a simulation

To update a simulation, do the following:

1. Open a workspace and select Tools > Simulations in the footer.
2. Select the simulation or click Actions > Open next to a simulation.
3. Update the mock servers and scenarios included in the simulation.

You can also click Actions next to a simulation to duplicate or delete it.