Apply behaviors to mocks that mimic slow or failing dependencies

A mock can contain multiple scenarios. Each scenario bundles its own request handling code with its own behaviors, the real-world faults like latency, errors, and rate limits you layer on top. Use scenarios to model the different situations your API might encounter and to test how your service handles a struggling dependency.

Manage scenarios in a mock

A scenario is a named variant of your mock that bundles its own request handling code and endpoints with its own behaviors, the real-world faults like delays and errors layered on top. Because all of a mock’s scenarios share the same mock URL, you can use scenarios to test different situations against a single mock, such as a standard request flow and a degraded flow under heavy load, without creating a separate mock for each one.

A scenario has two layers that work independently:

• Code — The request handling logic that defines what the scenario does, including its endpoints, response bodies and status codes, and any state it keeps across requests. This is the functional logic of the dependency you’re mocking. For example, one scenario might return a full list of items from an endpoint, while another returns an empty list.
• Behaviors — The real-world faults layered on top of the code, like latency, errors, and rate limits. They change how the scenario responds under stress without changing what it returns. For example, you can add a delay to test how your service handles a slow dependency.

You can apply behaviors to a scenario directly in the mock, or reuse a scenario in a simulation and override its behaviors for a specific run. To learn more, see Apply scenarios and behaviors.

Every mock starts with a default scenario. Scenarios appear as tabs in the mock editor. When you start the mock and send requests to it, it uses the default scenario. To run a different scenario, add the mock to a simulation and select the scenario there.

You can run a mock and its scenarios locally from the app or with the Postman CLI (postman mock run). Send the x-mock-scenario header to choose a scenario other than the default.

Create a scenario

1. Click the Items tab in the sidebar.
2. Click Mocks.
3. Select the mock you want to add a scenario to.
4. In the mock editor, click Add new scenario next to the scenario tabs.
5. Enter a name for the scenario.

The new scenario is based on the default scenario. In the Code pane, define the request handling logic for the scenario. Each scenario has its own code, so you can customize how it handles requests independently of other scenarios. To learn more, see Customize your mock.

To target a specific scenario in a request, include the x-mock-scenario: <scenario-name> header. In the Code pane, click Open in a new request next to the header key-value to open a new request with the header already filled in.

The default scenario

Click a scenario’s tab to view and edit its code and behaviors. One scenario in the mock is the default, marked with default: true in the config.yaml file. When you start the mock directly, it uses the default scenario, including any behaviors applied to it.

To run a specific scenario with behaviors applied, add the mock to a simulation and use the Select scenario dropdown list to choose the scenario you want. To learn more, see Apply mock scenarios to a Postman simulation.

Apply behaviors to a scenario

Apply behaviors to a scenario to introduce real-world disruptions like latency, errors, and rate limits. Behaviors saved on a scenario are its permanent failure profile. They define what the scenario represents, such as a slow dependency or a service returning errors, and can be reused across tests. Behaviors are available when you add the scenario to a simulation, where you can override them for a specific run without changing the scenario itself. To test how your service responds when multiple dependencies fail at the same time, use a simulation to coordinate multiple mocks together.

In the mock’s config.yaml file, behaviors are stored under the scenario’s conditions key.

1. Click the scenario tab you want to apply behaviors to.

2. In the mock editor toolbar, click Configure.

3. Turn on each behavior you want to apply, then enter a value where required:

   • Simulate error response — Return a specified HTTP status code.
   • Add response delay — Add a delay in milliseconds before the scenario sends a response, to mimic network latency.
   • Simulate rate limiting — Limit the scenario to a maximum number of requests per minute. Requests over the limit receive a 429 Too Many Requests response.
   • Chaos mode — Randomly fail a percentage of requests with 5xx status codes.

The scenario shows how many behaviors are applied, along with the value for each, such as 2000 ms.

To learn how a scenario’s behaviors are reused and overridden in a simulation, see Apply mock scenarios to a Postman simulation.