Quick answer: Test an asynchronous or SSE flow as an ordered scenario: start the long-running job, connect to the event stream, assert on the events as they arrive, and confirm the final completion state instead of polling one fixed response. SSE is modeled with a text/event-stream media type and an item schema describing one event, and the scenario engine can follow the real streaming system.
Why a single request does not fit async work
A long-running task does not return its result in one immediate response. It starts, emits progress over time, and completes later, often through an event stream. A single request that checks only the initial 202 or 200 cannot tell you whether the job finished or emitted the right events.
A scenario follows that lifecycle in order.
- A first step starts the job and extracts a job or stream reference.
- A later step connects to the SSE stream.
- Assertions check the streamed events and the final state.
How SSE is modeled
Server-sent events are represented with a text/event-stream media type and an OpenAPI 3.2 item schema that describes a single event. That keeps the streaming operation a normal path item rather than forcing it into a plain REST shape, and the protocol is preserved when editing rather than silently converted.
| Stage | What the scenario does |
|---|---|
| Start job | Send the request and extract the job or stream reference |
| Open stream | Connect to the event endpoint and read events as they arrive |
| Assert events | Check event types, order, and payload fields |
| Confirm completion | Assert the terminal event or final state is reached |
Assert across the streamed events
Streaming assertions differ from a one-shot check because the evidence arrives as a sequence of events.
- Assert the start step returns the expected accepted status and reference.
- Assert the stream opens and begins emitting events.
- Check the event types and order, since progress usually follows a defined sequence.
- Assert the payload fields on the events that matter.
- Confirm the terminal event marks the job complete.
Asserting the order and the terminal event matters, because a stream that emits progress but never reaches completion is a real defect even when every intermediate event looks fine. The engine runs the connected requests in the main process with streamed progress and a cancel action, so a hung stream can be stopped.
When a 200 hides a problem
An SSE or async step can return a healthy status while the event payload carries an error or an unexpected shape, just as a 200 can mask a contract break elsewhere. Assert the event fields against the item schema rather than trusting the connection status alone. If the expected events do not arrive, the result is inconclusive or a failure, not a pass based on silence.
Multi-protocol support is a supporting capability here. It lets the scenario follow the real system across SSE and other protocols, but it should not be treated as the headline. Scenarios stay outside the OpenAPI document with no x-scenarios keys and run against real connected requests rather than mocks.
Powerduck keeps the streaming steps and event assertions in the ordered run, so you can see the exact event where an async flow breaks.
Frequently asked questions
How is SSE represented in the spec? With a text/event-stream media type and an item schema describing one event. The operation stays a normal path item and is not converted into REST.
Can a single request verify a long-running job? No. It only sees the initial response. A scenario starts the job, follows the event stream, and confirms the terminal state across ordered steps.
What if the stream never completes? A missing terminal event is a failure even when intermediate events look correct. Assert completion so an unfinished job is caught.
The bottom line
Async and SSE work calls for an ordered scenario that starts the job, follows the event stream, asserts on the events, and confirms completion. Model the stream with the event media type and item schema, check event order and the terminal state, and do not let a healthy connection status hide a bad event payload or a job that never finishes. The scenario follows the real streaming system, which is what makes it more trustworthy than polling a single fixed response. Read more in the API scenario testing guide.
Top comments (0)