Mocking SSE: Streaming Events and How a Client Handles a Dropped Connection

Mocking a Server-Sent Events (SSE) endpoint requires a deeper understanding than simply returning a list. The key aspects to focus on are the framing of each event, the client's behavior during mid-connection, and how it handles connection drops and retries. A robust SSE mock should allow you to control the timing of events, inject faults, and simulate various scenarios to ensure the frontend correctly reacts to these events.

In a practical example, consider a job-progress UI that updates a progress bar based on events emitted by a backend during a long import process. Initially, using a mock that returns a JSON array of events caused the UI to render perfectly, as all events arrived simultaneously. However, in a real scenario, the stream could stall for several seconds between events, causing the browser to drop the connection and trigger the client's retry logic, which could result in erroneous event processing, such as the progress bar jumping backward. This type of issue would go unnoticed with a static JSON fixture.

The distinction between SSE and a regular HTTP response is crucial: SSE utilizes a long-lived HTTP connection with a specific framing. Each event is a block of lines ending with a blank line, and the connection remains open. The client automatically re-establishes the connection upon a drop and sends the last received event ID via the Last-Event-ID header.

To accurately test SSE behavior, a mock must let you control the event delivery schedule, simulate idle gaps, and inject delays to test behaviors like keep-alive and spinner updates. It should also allow you to close the connection mid-stream and verify the client's retry mechanism.

Building a time-aware mock involves using the web streams API in Node.js, which provides control over when events are pushed. This allows you to schedule events at specific intervals, representing real-world delays and idling periods. When simulating a dropped connection, the mock should close the stream and allow the client to reconnect automatically.

The test should then verify that the client resumes the stream correctly, starting from the last processed event ID, without reprocessing any events or getting stuck in an infinite loop.

Additional considerations include sending periodic comment lines as keep-alives to prevent intermediaries from closing idle connections prematurely. The mock should also handle explicit error events and ensure the UI correctly differentiates between recoverable interruptions and terminal failures. By focusing on these aspects, a mock can faithfully replicate the real streaming contract, enabling thorough testing of edge cases that are critical for a smooth streaming user experience.