Testing the "payment declined" flow means activating three or four mocks at once. Doing that manually every time? That's Tuesday energy we can fix.

Scenarios bundle mocks (and transforms) into named presets. Flip one switch, get the whole test state.

Record a scenario from traffic

The fastest scenario is one you don't hand-build. Hit Record scenario in the session strip, click through the flow in your app, then stop. FlowMock lists every request it captured - tick the ones that define the state, and it creates the overrides for you (including splitting one endpoint when query or body differed). Name it after the user story and flip it whenever you need that state again.

What's in a scenario

A scenario is a collection of published mocks that work together - plus optional transforms that patch bodies after the mock or upstream response:

Payment declined - 402 on pay, error toast data, updated cart state
Empty store - zero products, empty categories, "nothing here" banner copy
Slow checkout - delays on shipping quote and payment confirmation
Reproducible dates - freeze the scenario clock so transform now expressions stay stable for the whole team

Each scenario has a name, an id (scn_…), and a URL-friendly slug for sharing.

Switching scenarios

In the dashboard

Open your session (or the Sessions tab), pick a scenario from the dropdown. All mocks in that scenario activate for your session. Previous scenario mocks are replaced.

From CI

bash

curl -X PUT "https://api.flowmock.dev/api/v1/sessions/ci-42" \
  -H "Authorization: Bearer fmk_…" \
  -H "Content-Type: application/json" \
  -d '{"project":"checkout","environment":"staging","scenario":"scn_paymentDeclined"}'

Then run your tests with x-flowmock-session: ci-42. See Sessions API for details.

Clear a scenario

Set scenario to null to drop back to no active scenario - individual mock activations still apply.

Scenarios vs individual mocks

	Scenario	Individual mock
Best for	Whole test states	One-off tweaks
Switches	Many mocks at once	One mock at a time
Layers	Replaces previous scenario	Stacks on top of scenario

You can combine them: activate a scenario, then toggle an extra mock on top for edge cases.

Scenarios make reproduction easy. Share a link with the scenario id, and a teammate can activate the same bundle on their session. Same mocks, same responses, same bug - hopefully.

Discovering scenarios via API

CI pipelines can list available scenarios:

bash

curl "https://api.flowmock.dev/api/v1/scenarios?project=checkout&environment=staging" \
  -H "Authorization: Bearer fmk_…"

Returns scenario ids and names. See Scenarios API.

Mocks and overrides - building the mocks that go into scenarios
Transforms - body patches, expressions, frozen clock
QA sessions - session isolation basics
Getting started - first-time setup
Awareness headers - confirm which scenario applied on a request