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 into named presets. Flip one switch, get the whole test state.

What's in a scenario

A scenario is a collection of published mocks that work together:

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

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
QA sessions — session isolation basics
Getting started — first-time setup