Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Server
✓ import { Server } from 'mock-socket';
✗ const Server = require('mock-socket').Server;
Primary class for creating a mock WebSocket server. CommonJS `require` is supported but ESM `import` is preferred in modern Node.js environments.
WebSocket
✓ import { WebSocket } from 'mock-socket';
✗ import WebSocket from 'mock-socket';
The mock WebSocket client class, distinct from the global `WebSocket`. Not a default export. Used to manually create mock WebSocket clients or to replace the global `window.WebSocket`.
SocketIO
✓ import { SocketIO } from 'mock-socket';
✗ import { io } from 'mock-socket';
Provides a mock `io` constructor for Socket.IO clients. This symbol must be assigned to the global `window.io` for Socket.IO clients to use it.
Demonstrates basic usage of `mock-socket` by setting up a mock WebSocket server, connecting a simulated client, sending messages, and simulating connection closure. This example highlights the `Server` class and its event listeners for `connection` and `message`.
import { Server } from 'mock-socket';
// Simulate a client-side application that uses WebSocket
class WebSocketClientApp {
constructor(url) {
this.messages = [];
this.connection = new WebSocket(url);
this.connection.onopen = () => {
console.log('Client connected to:', url);
};
this.connection.onmessage = event => {
console.log('Client received:', event.data);
this.messages.push(event.data);
};
this.connection.onclose = () => {
console.log('Client disconnected');
};
this.connection.onerror = error => {
console.error('Client error:', error.message);
};
}
sendMessage(message) {
this.connection.send(message);
}
}
async function runMockTest() {
const fakeURL = 'ws://localhost:8080';
// Create a mock server instance
const mockServer = new Server(fakeURL);
// Listen for connections to the mock server
mockServer.on('connection', socket => {
console.log('Mock server: client connected!');
// Listen for messages from the connected client
socket.on('message', data => {
console.log('Mock server received from client:', data);
if (data === 'hello server') {
socket.send('hello client from mock server!');
}
});
// Simulate the server closing the connection after a delay
setTimeout(() => {
socket.close();
}, 500);
});
// Instantiate the client app, which will attempt to connect to the fakeURL
const app = new WebSocketClientApp(fakeURL);
app.sendMessage('hello server');
// Wait for some asynchronous operations to complete
await new Promise(resolve => setTimeout(resolve, 1000));
console.log('Messages received by client:', app.messages);
// Assertions would go here in a real test runner
if (app.messages.includes('hello client from mock server!')) {
console.log('Test passed: Client received expected message.');
} else {
console.error('Test failed: Client did not receive expected message.');
}
// Clean up the mock server
mockServer.stop();
console.log('Mock server stopped.');
}
// To run this example in a Node.js environment, you might need to globally stub WebSocket
// If running in a browser environment or a testing framework that stubs globals, this might be optional.
// For Node.js, ensure `global.WebSocket` is available or pass `{ mock: false }` to Server
// and manually assign `global.WebSocket = WebSocket;`
// In a test runner like Jest, you might do:
// beforeAll(() => { global.WebSocket = require('mock-socket').WebSocket; });
// afterAll(() => { delete global.WebSocket; });
// For this standalone example, we'll assume a context where WebSocket is available or shimmed.
// Or, if your client code explicitly imports WebSocket:
// const { WebSocket } = require('mock-socket'); // or import { WebSocket } from 'mock-socket';
runMockTest();
Debug
Known issues
breakingIn version 8.0.0, the `connection` event listener on the `Server` instance changed its signature. The first argument is now a `socket` reference (the individual client connection) instead of the `server` instance. This allows direct communication with the connected client.fixUpdate `mockServer.on('connection', socket => { ... })` to use the `socket` argument directly for sending messages (`socket.send()`) and listening for client messages (`socket.on('message', ...)`) instead of assuming the server instance. affects: >=8.0.0
breakingNode.js 6 support was dropped in version 8.1.0, and subsequently in 9.0.0, which now requires Node.js >= 8.fixEnsure your project's Node.js environment is version 8 or higher. Upgrade Node.js if necessary.
affects: >=8.1.0, >=9.0.0
gotchaBy default, creating a `new Server()` instance will automatically stub out the global `WebSocket` object, which is restored when the server stops. This can lead to unexpected behavior if multiple `Server` instances are created without proper management or if you need to use the real `WebSocket` in parallel.fixTo disable automatic global stubbing, pass `{ mock: false }` to the `Server` constructor: `new Server(url, { mock: false })`. You can then manually stub `window.WebSocket = WebSocket;` when and where needed, providing more control. affects: >=1.0.0
gotchaSocket.IO support in `mock-socket` is noted as limited. Not all Socket.IO features or complex scenarios may be fully supported or behave identically to a real Socket.IO server.fixWhen testing Socket.IO applications, thoroughly verify that `mock-socket` covers the specific Socket.IO features your client code relies on. For complex Socket.IO interactions, consider testing against a real (even if minimal) Socket.IO server or explore alternative mocking strategies if limitations are encountered.
affects: >=1.0.0
Errors
Common errors & fixes
Error: WebSocket is not defined
When running client-side code (e.g., a React app test) that uses the global `WebSocket` object in a Node.js environment (like Jest), the `WebSocket` global might not be present unless explicitly polyfilled or mocked by `mock-socket`.
fixEnsure that `mock-socket`'s global stubbing is active by creating a `new Server(url)` instance before the client code runs. If using `{ mock: false }`, manually assign `global.WebSocket = WebSocket;` (or `window.WebSocket` in a browser-like test environment) to the mock `WebSocket` from `mock-socket`. Cannot find name 'USVString'.
This error typically occurs in TypeScript projects when the TypeScript environment or `lib` settings are not correctly configured to include DOM types that define `USVString`.
fixEnsure your `tsconfig.json` includes `"lib": ["dom", "es2017"]` (or appropriate ES version) to provide standard DOM type definitions. This was a known issue in older `mock-socket` versions that was fixed in 8.0.5.
TypeError: app.connection.on is not a function
This error usually happens when attempting to use Socket.IO-style event listeners (`.on('event', ...)`) on a standard `WebSocket` mock, or vice versa, or if `window.io` was not correctly stubbed for a Socket.IO client.
fixVerify that you are using the correct mock for the client type: `WebSocket` for raw WebSockets and `SocketIO` (assigned to `window.io`) for Socket.IO clients. Ensure your client-side code is calling the appropriate methods (`.onmessage` for `WebSocket`, `.on('event')` for Socket.IO). Audit
Dependencies
No dependency data recorded yet.