> For the complete documentation index, see [llms.txt](https://docs.flxbl.io/flxbl/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.flxbl.io/flxbl/codev/service-virtualization/scenario-playbooks.md).

# 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/`:

{% code title="mocks/scenarios/order-delayed.scenario.yaml" %}

```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 } }
```

{% endcode %}

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.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.flxbl.io/flxbl/codev/service-virtualization/scenario-playbooks.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.