Create and run a simulation in Postman Simulator

A simulation groups one or more mocks of the services your app depends on, so you can run them together and see how your service behaves against the whole set. Run a simulation locally in the Postman app or from the Postman CLI, or deploy it to share with your team or use in CI.

To build a simulation from your own mocks, make sure you have at least one mock set up first.

A mock stays independent when you add it to a simulation. The same mock can be a member of several simulations, and deleting a simulation doesn’t delete its member mocks.

Run a simulation locally

To create and run a simulation on your machine, do the following:

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

2. Click Add mocks, then select the mocks you want to include. The simulation opens in a new tab to configure. You can also click Ask AI to create a simulation with Agent Mode.

   To try the feature without your own mocks, click Run a sample simulation on the Simulator’s start screen to create and run a simulation with sample mocks.

3. Set Route by to choose how requests reach each mock in the simulation:

   • URL path — Route requests to a mock using a unique path in the request URL. For example: http://localhost:4500/<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>

4. (Optional) Click Add mocks to add more mocks to the simulation.

5. (Optional) Expand a mock to change its scenario and apply behaviors, such as an error response.

6. Click Run to run the simulation locally. Postman serves the simulation at a local URL where you can send requests to its mocks. You can update the simulation’s name and view its logs and state as it runs.

You can also run a simulation locally from the Postman CLI with the postman simulation run command, or scaffold one with postman simulation create.

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.

To change the behaviors that apply to a simulation, see Apply scenarios and behaviors.

Deploy a simulation

Deploy a simulation to host its mocks as an always-available mock server that your team or CI pipelines can call. Deploying requires a Solo, Team, or Enterprise plan.

In the Postman app, deploy a simulation’s mocks together as a mock server. When you create a mock server from existing mocks, selecting more than one mock creates a simulated environment that serves all of them behind one address.

To deploy with the Postman CLI, use postman simulation push to upload the simulation and its member mocks to a Postman Cloud workspace, then postman simulation deploy to host it as a mock server.

Edit a simulation

To change a simulation, edit it directly in its editor: update its mocks, scenarios, and behaviors, and change how requests route. You can also view the simulation file in the YAML tab, which is editable in Local View and read-only in Cloud View.

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.

Postman stores each simulation in its own folder in your local Git repository, at postman/simulations/<simulation-name>/<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.

Postman also adds a starter context document to the simulation’s folder, named <simulation-name>.context.md. This Markdown file captures what the simulation stands in for, such as its mocks and the upstream services they represent, for you or an agent to fill in. It’s a reference for your team and isn’t required to run the simulation.