Quick answer: API scenario testing runs an ordered sequence of real, connected requests that model a business flow, where a value from one response can feed a later request and assertions run at every step. It verifies that the whole flow still works, instead of trusting a single endpoint response. The engine runs in the desktop main process, progress is streamed, and a run can be cancelled.
Why a single request is not enough
Hitting one endpoint and reading a 200 tells you very little about a real flow, because most business behavior spans several calls. A login returns a token, a second call uses it to create a resource, and a third reads it back. Each request can look fine on its own while the chain between them is broken.
A scenario treats that chain as the unit under test.
- It is an ordered sequence of requests.
- A value extracted from one response can be passed into a later request.
- Assertions run at each step on the status, headers, or response fields.
This matches the job to be done: verify the API and business flow with real, connected requests rather than trusting one response.
How a scenario is built and run
The scenario engine, runScenario from the openapi-cli package, executes in the desktop main process. Progress is streamed as the steps run, and you can cancel a long run instead of waiting it out.
| Element | Role |
|---|---|
| Ordered steps | Fix the sequence the business flow requires |
| Extracted variables | Carry a token, id, or value from one step to the next |
| Per-step assertions | Check status, headers, or response fields at each stage |
| Streaming progress | Show where the run is in real time |
| Cancel action | Stop a run that hangs or goes wrong |
Scenarios are never stored inside the OpenAPI document. There are no x-scenarios keys; the scenario lives in its own workflow, which keeps the spec clean and the test separate.
What it gives you that a mock does not
A local mock is useful for building a client against stable responses, but it does not verify the real backend. Importing a spec or running a mock does not deploy or replace the real backend, and a scenario is meant to run against real, connected requests. That distinction is what lets a scenario catch a broken chain rather than just replay a fixed answer.
When a run finishes, you can export a self-contained HTML report in ten built-in languages. Known credential fields are redacted automatically, and large payloads are folded so the report stays readable.
Honest limits
A scenario only covers the steps and branches you define, and it does not prove the system is correct outside that flow. A passing run says the ordered requests met their assertions this time, not that every path works. Multi-protocol support is a supporting capability here, letting the scenario follow the real system across HTTP, SSE, WebSocket, GraphQL, gRPC, and MCP rather than being a reason to buy on its own.
Powerduck opens scenario testing as one of the two core workflows, keeping the connected requests and the per-step evidence together so you can see exactly where a flow holds or breaks.
Frequently asked questions
How is scenario testing different from a single API test? A single test checks one endpoint. A scenario chains ordered, connected requests with extracted variables and assertions at each step to verify a whole business flow.
Are scenarios stored in the OpenAPI file? No. Scenarios are never stored in the document and there are no x-scenarios keys. They live in the separate scenario workflow.
Does a mock replace a scenario? No. A mock replays fixed responses and does not verify the real backend. A scenario runs connected requests against the real flow to catch a broken chain.
The bottom line
API scenario testing is verification of a connected, ordered flow rather than a single response. It passes values between real requests, asserts at every step, and shows where the chain breaks, while keeping the tests outside the OpenAPI document and separate from mocks. A passing run covers only the flow you defined, not the whole system, but it answers the question that one-off requests cannot: whether the business flow still works end to end. Read more in the API scenario testing guide.
