Registry / testing / vitest-mock-socket

vitest-mock-socket

library2.1.0jsnpmunverified

A library to mock and assert WebSocket interactions in Vitest tests. Version 2.1.0 is current, released with support for Vitest 2+ and Node >=24. It intercepts global WebSocket connections and provides an API to simulate server events, send/receive messages, and assert on WebSocket state. Compared to alternatives like mock-socket, it is tailored for Vitest, integrates with Vitest's test lifecycle, and ships TypeScript definitions. Low release cadence, focused on stability.

testing

npm install vitest-mock-socket

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · VITEST-MOCK-SOCKET

vitest-mock-socket

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

createMockServer

✓ import { createMockServer } from 'vitest-mock-socket'

✗ const createMockServer = require('vitest-mock-socket').createMockServer

ESM-only; named export. CommonJS require will not work.

mockWebSocket

✓ import { mockWebSocket } from 'vitest-mock-socket'

Named export for creating a mock WebSocket instance.

WebSocketMockServer

✓ import type { WebSocketMockServer } from 'vitest-mock-socket'

✗ import { WebSocketMockServer } from 'vitest-mock-socket'

Type-only export; do not import as value.

Creates a mock WebSocket server, connects a real WebSocket, and asserts received message.

import { describe, it, expect, vi } from 'vitest'; import { createMockServer } from 'vitest-mock-socket'; describe('WebSocket tests', () => { it('should receive a message', async () => { const server = createMockServer(); const url = 'ws://localhost:1234'; const ws = new WebSocket(url); server.url = url; server.on('connection', (socket) => { socket.send('hello from server'); }); const onMessage = vi.fn(); ws.onmessage = (event) => onMessage(event.data); await vi.waitFor(() => { expect(onMessage).toHaveBeenCalledWith('hello from server'); }); server.close(); ws.close(); }); });

Debug

Known issues

breakingRequires Node >=24.0.0

fix

Update Node.js to v24 or later, or pin to version 1.x

affects: >=2.0.0

breakingESM-only package; does not support CommonJS require()

fix

Use import syntax and ensure package.json has 'type': 'module'

affects: >=2.0.0

deprecatedmockWebSocket() replaced by createMockServer() in v2

fix

Replace mockWebSocket() with createMockServer()

affects: >=2.0.0

gotchaGlobal WebSocket is mocked; avoid importing other WebSocket mocks

fix

Use only one WebSocket mock library, or ensure vitest-mock-socket is imported last

affects: >=2.0.0

gotchaServer url must match WebSocket constructor url exactly

fix

Set server.url to the exact url used in new WebSocket()

affects: >=2.0.0

Errors

Common errors & fixes

Error: [vitest-mock-socket] WebSocket constructor is not available. Ensure you are running in a Vitest test environment.

Library uses global WebSocket which may be mocked by other libraries first.

fix

Import vitest-mock-socket before any other WebSocket mock or polyfill.

TypeError: createMockServer is not a function

Using CommonJS require() on an ESM-only module.

fix

Use ES module import syntax: import { createMockServer } from 'vitest-mock-socket'

Error: Expected server.url to be set before creating WebSocket

Server url not assigned before instantiating WebSocket.

fix

Set server.url to the WebSocket URL before new WebSocket(url).

Upgrade

Version history

2.1.0latest on npm

Audit

Dependencies

vitestrequiredpeer dependency; requires Vitest >=2 to run tests

Agent activity

13 hits · last 30 days

node

Bingbot

Resources

githubhttps://github.com/andrewangelle/vitest-mock-socket ↗

packagevitest-mock-socket ↗

homepagehttps://github.com/andrewangelle/vitest-mock-socket#readme ↗