Create and run simulations in Postman

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

Simulations are most useful when you want to test how your service responds when multiple dependencies fail at the same time. For example, you can combine a mock server that simulates a slow auth service with one that returns errors from an inventory API, then observe how your service handles both conditions together.

Simulations can be applied to mock servers deployed from a mock. For each mock server, you select a scenario and can override its conditions for the simulation without changing the scenario itself. This lets you push a scenario further for a specific test run. For example, a scenario with 500ms latency can be overridden to 5000ms for a load test while the original scenario stays unchanged.

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

Create a simulation

Create a simulation to apply failure scenarios to one or more mocks. Before you create a simulation, make sure you have at least one mock set up and deployed as a mock server.

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. Select the mocks you’d like to add to the simulation.

6. Choose how requests access mocks in the simulation:

   • URL path — Route requests to a mock 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 using a request header while sharing the same simulation URL. For example: x-mock-slug: <mock-slug>

7. Click Create simulation.

Simulations show in the left sidebar under Mock Servers. You can select a simulation to view its details, including the mocks 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 mocks and scenarios. This file is used to start the 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 mocks and scenarios included in the simulation. You can also use Agent Mode to quickly update the simulation file.

Apply scenarios to a simulation

For each mock in a simulation, select the scenario you want to use. The simulation uses the conditions defined on that scenario, such as errors, latency, and rate limits. You can override any of these conditions for the simulation without changing the scenario itself. You can select scenarios and override conditions before or during a simulation.

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

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

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

4. For each mock, use the Select scenario dropdown list to choose a scenario. The scenario’s conditions are shown, along with the value for each.

5. (Optional) To override a condition for the simulation, click Customize for this simulation next to a condition, select a new value, and click to save. The scenario’s original value is shown for reference. You can override the following conditions:

   • Simulate Error Response — Simulate error responses by returning a specified HTTP status code.
   • Add Response Delay — Simulate network latency by adding a delay (in milliseconds) before the 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 Response 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 Response or Chaos Mode.

6. (Optional) To clear the overrides for a mock and return to the scenario’s conditions, click Reset.

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

Start a simulation

You can start all 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 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 mocks and scenarios in the simulation. You can also turn off the toggle next to a mock to exclude it from the simulation.

4. Click Start to start the simulation.

5. Send requests to the 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 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 mocks included in the simulation.

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

You can filter logs by path, mock, 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 mock.

Edit a simulation configuration

You can edit the configuration for a simulation to update the 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 mocks in the simulation. This can be either path or header.
   • mocks — The mocks included in the simulation. Each entry has an id, a path to the mock’s config.yaml file, and a scenarios list. Each scenario entry has an id, a path to the scenario’s implementation file, and an optional overrides block. Conditions you override for the simulation are stored under overrides.conditions (for example, latency.delay_ms), which leaves the scenario’s own conditions unchanged.

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 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 mocks and scenarios included in the simulation.

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