how to test websockets in cypress

TL;DR

Cypress cannot intercept WebSocket frames with cy.intercept(). Test websocket flows by controlling the server side, asserting on UI effects, or driving the socket from cy.window().

Error

(Not an error; a limitation guide. The gap: cy.intercept() does not see WebSocket traffic.)

Steps

1. Accept the limitation: plan assertions on UI effects of socket messages, not the frames. Expected: the right test target.
2. Control the server: in tests, trigger server pushes deterministically via a test endpoint. Expected: deterministic messages.
3. From the test, access the socket: cy.window().then(w => w.socket.emit('test-event')). Expected: direct control when needed.
4. Assert the UI updates: cy.get('[data-cy=message]').should('contain', 'hello'). Expected: behavior verified.
5. For protocol-level testing, use a Node-based test outside Cypress. Expected: the right tool for the job.

When to use

• Apps with WebSocket features under Cypress test.
• You need deterministic socket behavior.

When not to use

• REST APIs (intercept works fine).
• Protocol conformance (use a socket client library).

Tool compatibility

• Cypress 10 through 14; app socket clients.

Variant phrasings

Cypress websocket testing

The general topic; UI-effect assertions.

Intercept websocket in Cypress

Not supported; control the server instead.

Why it happens

cy.intercept() works at the HTTP layer. WebSockets upgrade past HTTP, so the interception point never sees them.

Edge cases

• Socket.io falls back to polling sometimes; those polls ARE interceptable.
• Reconnection logic needs kill-and-restore tests; do them at the server level.
• Do not assert on message timing; assert on eventual UI state.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_6pN8n5yrrgNY2Ij8yclUpQ