Registry / testing / jest-websocket-mock

jest-websocket-mock

library2.5.0jsnpmunverified

A library for mocking WebSocket servers in Jest tests. Version 2.5.0 is the current stable release with no fixed cadence. It provides a WS class to simulate a WebSocket server, track messages, and assert interactions. Supports JSON protocol auto-serialization, error simulation, and graceful close. Ships TypeScript definitions. Key differentiators: built-in connected/closed/nextMessage promises for async test flow, static clean() method to reset between tests, and compatibility with popular patterns like redux-saga and react hooks via example code.

testing

npm install jest-websocket-mock

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · JEST-WEBSOCKET-MOC

jest-websocket-mock

testingjavascriptv2.5.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.

✓ import WS from 'jest-websocket-mock'

✗ import { WS } from 'jest-websocket-mock'

WS is the default export. Named export syntax will fail.

✓ const WS = require('jest-websocket-mock')

✗ const { WS } = require('jest-websocket-mock')

CommonJS require yields the default export directly.

WS (TypeScript)

✓ import WS from 'jest-websocket-mock'

✗ import WS = require('jest-websocket-mock')

TypeScript should use ES default import syntax. The package includes types.

Creates a mock WebSocket server, connects a client, sends a message, and asserts the server received it.

import WS from 'jest-websocket-mock'; const server = new WS('ws://localhost:1234'); const client = new WebSocket('ws://localhost:1234'); await server.connected; client.send('hello'); expect(server).toHaveReceivedMessages(['hello']); WS.clean();

Debug

Known issues

breakingIn version 2.0.0, WS.clean() was introduced and must be called after each test to avoid port conflicts.

fix

Add WS.clean() in afterEach or afterAll to close all connections.

affects: <2.0.0

breakingIn version 2.0.0, the import changed from named to default export.

fix

Change import { WS } from 'jest-websocket-mock' to import WS from 'jest-websocket-mock'.

affects: <2.0.0

deprecatedThe 'connected' promise resolves every time a new connection is made; do not assume it resolves only once.

fix

Track connections manually if you need per-connection state.

affects: >=2.0.0

gotchaUsing the same URL for multiple WS instances can cause unexpected behavior as mock-socket may reuse ports.

fix

Use distinct URLs or clean up with WS.clean() before creating new instances.

affects: >=1.0.0

Errors

Common errors & fixes

Can't resolve 'mock-socket'

jest-websocket-mock depends on mock-socket, but it is not installed.

fix

Run npm install --save-dev jest-websocket-mock mock-socket

TypeError: WS is not a constructor

Importing named export instead of default export (e.g., import { WS } from 'jest-websocket-mock').

fix

Change to import WS from 'jest-websocket-mock'

Timeout - Async callback was not invoked within the 5000 ms timeout specified by jest.setTimeout.

Forgetting to call WS.clean() between tests, causing port exhaustion or hanging connections.

fix

Add afterEach(() => { WS.clean(); });

Upgrade

Version history

2.5.0latest on npm

Audit

Dependencies

mock-socketrequiredUnderlying mock WebSocket implementation used by jest-websocket-mock

Agent activity

12 hits · last 30 days

node

Amazon

Resources

githubhttps://github.com/romgain/jest-websocket-mock ↗

packagejest-websocket-mock ↗

homepagehttps://github.com/romgain/jest-websocket-mock#readme ↗