Registry / testing / cypress-mock-websocket-plugin

cypress-mock-websocket-plugin

library2.0.0jsnpmunverified

A Cypress plugin to mock WebSocket connections using a cy.intercept-style API. Current stable version is 2.0.0. It allows defining request/response pairs that the app receives during Cypress tests, supports partial matching via ts-pattern, and works with rxjs WebSocket and Apollo GraphQL subscriptions. Key differentiators: runs on top of Cypress's built-in WebSocket communication (no separate mock server needed), supports both a custom constructor and native WebSocket API, and provides static response registration as well as dynamic request handlers.

testing

npm install cypress-mock-websocket-plugin

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · CYPRESS-MOCK-WEBSO

cypress-mock-websocket-plugin

testingjavascriptv2.0.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

default (side effect)

✓ import 'cypress-mock-websocket-plugin'

✗ import { mockWebSocket } from 'cypress-mock-websocket-plugin'

The plugin is a side-effect import that adds cy.mockWebSocket and cy.registerSocketRequestResponse commands. Do not use named imports.

cy.mockWebSocket

✓ cy.mockWebSocket(url, options?)

✗ cy.mockWebSocket({ url }) or cy.mockWebSocket(url, { useNative: true }) without importing

Available globally after import. First argument is URL string (not object). Options include useNative, webSocketCtorName, connectionResponseMessage.

cy.registerSocketRequestResponse

✓ cy.mockWebSocket(url).registerSocketRequestResponse(request, response)

✗ cy.registerSocketRequestResponse(request, response) without chaining

Must be chained after cy.mockWebSocket() because it registers on that mock instance.

Creates a mocked WebSocket endpoint, registers a request/response pair, visits the app, and asserts the response appears in the DOM.

import 'cypress-mock-websocket-plugin' const request = { type: 'request', payload: 'PING' } const response = { type: 'response', payload: 'PONG' } cy.mockWebSocket('ws://example.com/ws') .registerSocketRequestResponse(request, response) .visit('/') .contains('PONG')

Debug

Known issues

breakingThe initial response must be moved to the options object.

fix

Use { connectionResponseMessage: initialResponse } in options instead of passing as second argument.

affects: >=2.0.0

gotchaCypress uses WebSockets internally; mocking native WebSocket may interfere.

fix

Set { useNative: true } to mock the native WebSocket API explicitly.

affects: >=1.0.0

deprecatedDirect passing of initial response as second argument is deprecated.

fix

Move to options object: { connectionResponseMessage: initialResponse }

affects: <2.0.0

gotchaPartial matching via ts-pattern works only with object requests; plain strings may not match.

fix

Ensure request objects have similar shape; use a handler function for custom matching.

affects: >=1.0.0

Errors

Common errors & fixes

CypressError: cy.mockWebSocket() must be called before cy.visit()

Mock registration order – the WebSocket connection must be intercepted before the app loads.

fix

Move cy.mockWebSocket() before cy.visit() in your test.

TypeError: Cannot read properties of undefined (reading 'registerSocketRequestResponse')

Forgetting to chain after cy.mockWebSocket() or calling on a non-mocked page.

fix

Always chain: cy.mockWebSocket(url).registerSocketRequestResponse(...)

The request does not match any registered mock

Partial matching failure due to extra/ missing fields or different data types.

fix

Use a handler function for dynamic matching: .registerSocketRequestResponse(req => {...})

Upgrade

Version history

2.0.0latest on npm

Audit

Dependencies

ts-patternrequiredUsed internally for partial request matching

Agent activity

11 hits · last 30 days

node

Resources

githubhttps://github.com/coco1979ka/cypress-websocket-plugin ↗

packagecypress-mock-websocket-plugin ↗

homepagehttps://github.com/coco1979ka/cypress-websocket-plugin#readme ↗