Cypress `cy.intercept()` cannot stub WebSocket frames, so how do you test a socket-fed UI?

## The limitation, stated exactly Cypress documents two separate facts about WebSockets, and conflating them causes most of the confusion: - **Your application's WebSocket traffic works as expected during a test.** Sockets connect, frames flow, the UI updates. Nothing about running under Cypress breaks them. - **Cypress does not intercept that traffic.** Stubbing or mocking individual WebSocket **messages or frames** is not natively supported by `cy.intercept()`. So a live-alerts panel on a weather dashboard renders fine under test as long as a real server is pushing to it. What you cannot do is write a route that fabricates the alert frame, the way you would stub a `GET /api/forecast` response. ## Why an intercept cannot reach a frame `cy.intercept()` is built around a **request/response pair**: something is sent, a rule matches it, a response is produced or observed, and the exchange is over. A WebSocket is the opposite shape — one long-lived, full-duplex channel over which either side sends messages whenever it likes, with no per-message request to match and no per-message response to supply. There is nothing for a route matcher to key on and nothing for a static response to replace. ## The three documented strategies 1. **Stub the application's callbacks.** Use `cy.stub()` to replace the handler your app registers on the browser WebSocket API — its `onmessage`, or the wrapper it puts around one — and call it directly with the payload you want to simulate. Fastest and fully deterministic, and it exercises **only** the rendering path: nothing about your socket wiring, reconnect logic, or message parsing is under test. 2. **Drive the message from your server.** Have the server send the frame in response to something the test triggers — typically a `cy.request()` to a test-only endpoint that publishes an alert. The frame travels the real channel, so the socket client, the parsing, and the render are all exercised. 3. **Introduce a helper client outside the browser.** Run a small Node process that opens its own connection to your socket server and exposes an HTTP surface; the test drives it with `cy.request()` so it can send and receive as a second participant. This is what you reach for when the scenario genuinely needs two parties, such as one station operator publishing an alert that another dashboard must receive. | Strategy | What it exercises | What it costs | |---|---|---| | Stub the app's handler | Rendering only | Couples the test to internals | | Server pushes on cue | Socket, parsing, render | A test-only endpoint to maintain | | Helper client outside the browser | A real second participant | A process to run and clean up | ## Choosing between them - If the assertion is about **what the UI does with a message** — an alert banner turns red above a wind-speed threshold — stubbing the handler is proportionate and fast. - If the assertion is about **the feature working**, use the server-driven route, because a stubbed handler stays green while the socket URL, the subprotocol, or the parsing is broken. - Reach for the helper client only for genuinely multi-party scenarios; it is the most machinery and the most to tear down between specs. - Whichever you pick, keep the **trigger** inside the test. A test that waits for a message some background job might send is not deterministic, whatever seam it uses. ## Traps worth naming - **Do not expect a route matcher to help.** Even though a request's `resourceType` has `'websocket'` among its possible values, that is a classification of a request, not a handle on the frames of a live channel — and `resourceType` is deprecated as a matcher. - **Do not model the socket as slow HTTP.** Retrying an assertion until a frame happens to arrive turns a missing trigger into a timing flake. - **Do not stub the constructor away wholesale** unless the test really is only about rendering; you lose every signal that the real channel works. - **Do not confuse "not intercepted" with "not supported".** The traffic runs; only the interception does not exist. ## What to remember The limitation is architectural, not a missing feature flag: `cy.intercept()` speaks request/response and a WebSocket is a channel. Move the seam to a place you control — the app's handler, your server, or a second client — and choose the one whose blast radius matches what the test claims to prove.