Scenario playbooks

Rules describe how a single service behaves. A scenario describes a named test case spanning multiple services — for example, an order in a delayed state where the shipment is held in customs and the carrier's ETA endpoint returns an error. Arming a different scenario changes the responses of every service it covers, so the same clickthrough exercises a different code path.

A playbook

Playbooks are committed at the repository level, under mocks/scenarios/:

mocks/scenarios/order-delayed.scenario.yaml

apiVersion: sfp.flxbl.io/mocks/v1
kind: scenario
name: order-delayed
steps:
  - service: OrderStatusApi
    request: { method: GET, path: /orders/A-1001/status }
    response: { status: 200, body: { status: DELAYED, eta: '2026-06-25' } }
  - service: ShippingTrackerApi
    request: { method: GET, path: /track/A-1001 }
    response: { status: 200, body: { carrier: AusPost, location: Held at customs } }
  - service: ShippingTrackerApi
    request: { method: GET, path: /carriers/AusPost/eta }
    response: { status: 503, body: { error: carrier eta unavailable } }

Every playbook on the branch is loaded when a mock session is activated and appears in sfp mock scenarios. Note that paths are concrete — the org will make the same calls during replay, so a playbook is written for specific test records (it is good practice to note the record in a header comment).

Arming and replaying

sfp mock scenario order-delayed

Arming applies the scenario's responses on top of the baseline for exactly the services it touches. The replay semantics:

• When a scenario contains the same request several times, the responses are served in declaration order as the org repeats the call. After the sequence is exhausted, the last response continues to be served. This models state that changes between calls — for example a feature flag that reads as enabled on the first call and disabled on subsequent calls.
• All steps of a scenario are armed as one operation. Every service the scenario covers serves that scenario's responses; a partial application — one service on the scenario, another on its baseline rules — cannot occur.
• sfp mock scenario rewind resets all sequences to their first response, allowing the same test case to be repeated without re-arming.
• sfp mock scenario off disarms; the baseline rules (and any session edits) apply again. Arming a different scenario switches directly.

Sequences advance per request path independently — a scenario does not enforce the order in which different endpoints are called. Author scenarios to match the calls the org actually makes rather than relying on cross-endpoint ordering.

Capturing instead of authoring

For longer test cases, a scenario can be captured from a live session instead of authored by hand:

1. Start a capture (a named recording) through the control-plane API.
2. Perform the clickthrough in the review environment — every request, and the response it was served, becomes a step.
3. Stop the capture and review the steps; edit any response that should differ on replay — for example, changing a recorded success into an error response to produce a failure case.
4. Arm it, replay it, and once it is worth keeping, export it as a playbook file and commit it.

Captured scenarios live with the session; exported playbooks live in git and load into every future session on that branch. If a captured scenario and a playbook share a name, the capture wins for that session.

What scenarios are for — and not for

Scenarios provide reproducible org behaviour for clickthrough testing, demos and bug reproduction — whether driven by a tester in the UI, a developer at the API, or an agent automating either. They compile down to the same rules engine underneath, so anything a scenario does can also be expressed as committed rules; scenarios are the practical form for cross-service, sequence-dependent cases.

They are not a replacement for Apex tests or validation: a scenario asserts nothing by itself. It makes the org behave a particular way so that a person, a UI test or an agent can verify the behaviour built on top of it.