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 local mock servers, 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 mock servers. Before you create a simulation, make sure you have at least one local mock server set up. To learn how, see Simulate your API using a Git-backed mock server.

To create a simulation, do the following:

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

2. Click Create simulation.

3. Select the mock servers you’d like to add to the simulation. To remove a mock server from the simulation, click Actions and select Remove mock.

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

   • 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 mock server 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.

A simulation file is created in your local Git repository with the configuration for the simulation.

About the simulation file

When you create a simulation, Postman creates a simulation file in your local Git repository with the configuration for the simulation, including the mock servers and scenarios. This file is used to start the mock servers 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 mock servers and scenarios included in the simulation. You can also use Agent Mode to quickly update the simulation file.

Start a simulation

You can start all mock servers in the simulation or start them individually. You can also start a simulation using the Collection Runner or the Postman CLI.

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

1. Open a workspace and select Tools > Simulator in the footer.
2. Click the simulation you’d like to start.
3. (Optional) Update the mock servers and scenarios in the simulation.
4. Click Start all to start all mock servers in the simulation, or click Start mock server to start an individual mock server.
5. Send requests to the mock server URLs and observe the responses with the simulated conditions applied.

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.

Update a simulation

To update a simulation, do the following:

1. Open a workspace and select Tools > Simulator in the footer.
2. Click the simulation or select 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.