Scenario testing for REST APIs: writing user-journey tests from OpenAPI
Single-request testing answers a narrow question: does this endpoint, given these inputs, return this status right now? It cannot answer the question that actually breaks releases: can a user complete the job? A user never calls one endpoint. They create a resource, wait for it to become ready, attach something to it, act on it, and verify the result. Each request depends on the previous one's…
Scenario testing fills the gap left by single-request testing for REST APIs. While individual requests can confirm whether an endpoint returns the expected status for specific inputs, they cannot assess whether a user can successfully complete a job across multiple requests. User interactions typically involve a chain of dependent requests, with each one relying on the response from the preceding one. Traditional request-level tests often miss such integration bugs that only surface in the production environment.
Scenario testing addresses this gap by making dependencies explicit. The outcome of one request becomes input to the next, and assertions are run on the accumulated state. This approach extracts variables from one response to use as inputs for subsequent requests, ensuring the entire user journey is tested.
To create scenarios, teams should derive them from the OpenAPI specification. State machines defined in the spec can be identified by their status enums, marking them as potential scenario candidates. For each legal transition defined in the schema, a happy-path scenario should be written, along with an illegal-transition scenario to test for error handling.
The anatomy of a scenario consists of a sequence of steps, each containing a request, extraction rules, and assertions. These steps are deliberately simple, focusing on HTTP verbs, paths, JSONPath assertions, and template variables.
Deriving scenarios from the OpenAPI spec involves identifying state machines, listing legal transitions, following resource nesting, pairing writes with reads, and using 4xx responses as test cases. Error branches, which often lack detailed documentation, become valuable contract verification opportunities when tested through scenarios.
Modern APIs frequently involve asynchronous patterns such as polling and server-sent events (SSE). Scenario testing should explicitly handle these cases. For polling, a scenario may need to repeatedly GET a resource until a desired status is reached or a timeout occurs, with an interval for the polling checks. For SSE, the scenario opens a connection, triggers an action, and asserts the expected events arrive within a specified time window.
Implementing these scenarios with plain HTTP clients can be cumbersome, but spec-aware testing tools can simplify the process.
Running the same scenario against two environments - a mock server before the backend is available, and staging after it is deployed - is a highly effective practice. This allows frontend and backend teams to synchronize on the journey, catch contract divergences early, and gate merges based on successful mock runs. A useful scenario report should provide detailed information about the failing step, expected versus actual values at specific JSON paths, full request and response exchanges, and extracted variables to pinpoint issues like missing extraction paths due to added wrapper envelopes.
To begin, teams should focus on writing three scenarios that represent the primary customer actions, such as subscribing, changing plans, and canceling for a billing API, or uploading, processing, and downloading for a document service. These scenarios should be run against both the mock server and staging environment to ensure the API contract is correctly implemented before proceeding with further development.
Written by urgent.news from Dev.to's reporting — not their text. Machine-written — may contain errors; check the original before relying on it.
