Registry / testing / vitest-websocket-mock

vitest-websocket-mock

library0.5.0jsnpmunverified

A mock WebSocket server for Vitest tests, forked from jest-websocket-mock. Current stable version is 0.5.0. It provides a WS class to create mock servers, track messages, and send responses, with Vitest-specific matchers and helpers. Works with Vitest >=3 and TypeScript types are included. Key differentiators: seamless Vitest integration (no Jest dependency), supports jsonProtocol, and includes async promises (connected, nextMessage, closed) for precise test timing.

testing

npm install vitest-websocket-mock

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · VITEST-WEBSOCKET-M

vitest-websocket-mock

testingjavascriptv0.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.

default (WS)

✓ import WS from 'vitest-websocket-mock'

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

WS is a default export, not a named export. Named imports will fail.

WS type (TypeScript)

✓ import type WS from 'vitest-websocket-mock'

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

Use 'import type' for type-only imports to avoid value import.

WS.clean

✓ import WS from 'vitest-websocket-mock'; WS.clean()

✗ import { clean } from 'vitest-websocket-mock'

clean is a static method on the default WS class, not a separate export.

Demonstrates creating a mock WebSocket server, connecting a client, sending and receiving messages, and cleaning up after the test.

import WS from 'vitest-websocket-mock'; import { describe, it, expect, afterEach } from 'vitest'; describe('WebSocket mock', () => { afterEach(() => { WS.clean(); }); it('should send and receive messages', async () => { const server = new WS('ws://localhost:1234'); const client = new WebSocket('ws://localhost:1234'); await server.connected; client.send('ping'); const message = await server.nextMessage; expect(message).toBe('ping'); server.send('pong'); // client receives message (can't await directly; use an event listener) // For a complete test, you'd wrap client.onmessage in a Promise. server.close(); }); });

Debug

Known issues

gotchaThe 'connected' promise resolves once per connection, but if you have multiple connections, you must await a new promise for each. Use server.connected multiple times or track connections manually.

fix

Await server.connected again for each new incoming connection, or use server.on('connection', handler).

affects: >=0.0.0

gotchaThe mock server uses a real WebSocket port; ensure the port (e.g., 1234) is not in use by other tests or processes to avoid connection failures.

fix

Use a unique port per test file or set a random port and pass it to both server and client.

affects: >=0.0.0

breakingVersion 0.5.0 requires vitest >=3. Previous versions may not be compatible with Vitest 3.

fix

Upgrade vitest to version 3 or higher. If using an older vitest, stick with vitest-websocket-mock <0.5.0.

affects: 0.5.0

gotchaThe 'nextMessage' promise resolves with the next message received by the server. If multiple messages arrive before you await it, you may miss some. You must await sequentially or implement queuing.

fix

Wrap message reception in loops or use server.on('message', handler) to collect all messages.

affects: >=0.0.0

deprecatedThe 'jsonProtocol' option is currently stable, but consider that serialization is automatic; avoid manual JSON.parse/stringify when using it.

fix

When jsonProtocol is true, send and receive JavaScript objects directly; no manual conversion needed.

affects: >=0.0.0

Errors

Common errors & fixes

TypeError: WS is not a constructor

Importing WS as a named export instead of default export.

fix

Use 'import WS from 'vitest-websocket-mock'' (default import).

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

The test timed out waiting for server.connected because the WebSocket connection failed (port busy or server not started).

fix

Ensure the port is available, and consider increasing timeout with vi.setTimeout(10000) for slow environments.

Error: connect ECONNREFUSED ::1:1234

The mock server URL uses IPv6 but the system prefers IPv4 or vice versa.

fix

Use 'ws://127.0.0.1:1234' instead of 'ws://localhost:1234' to force IPv4.

Property 'connected' does not exist on type 'WS'

Using TypeScript with a version that doesn't include type definitions for WS.

fix

Install types: 'npm install -D @types/ws' or use a recent version of vitest-websocket-mock that ships types.

Upgrade

Version history

0.5.0latest on npm

Audit

Dependencies

vitestrequiredVitest is the test framework; this package is designed as a companion for Vitest and is only used within Vitest environments.

Agent activity

12 hits · last 30 days

node

Resources

githubhttps://github.com/akiomik/vitest-websocket-mock ↗

packagevitest-websocket-mock ↗

homepagehttps://github.com/akiomik/vitest-websocket-mock#readme ↗