WebSocket and Socket.IO Mocking Library

Common errors

• Error: WebSocket is not defined

  cause 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`.
  fix Ensure 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'.

  cause 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`.
  fix Ensure 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

  cause 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.
  fix Verify 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).

Warnings

• breaking In 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.
  Fix: Update `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.
• breaking Node.js 6 support was dropped in version 8.1.0, and subsequently in 9.0.0, which now requires Node.js >= 8.
  Fix: Ensure your project's Node.js environment is version 8 or higher. Upgrade Node.js if necessary.
• gotcha By 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.
  Fix: To 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.
• gotcha Socket.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.
  Fix: When 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.

Install

• npm install mock-socket npm
• yarn add mock-socket yarn
• pnpm add mock-socket pnpm

Imports

• Server
  wrong:

  const Server = require('mock-socket').Server;

  correct:

  import { Server } from 'mock-socket';

  Primary class for creating a mock WebSocket server. CommonJS `require` is supported but ESM `import` is preferred in modern Node.js environments.
• WebSocket
  wrong:

  import WebSocket from 'mock-socket';

  correct:

  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
  wrong:

  import { io } from 'mock-socket';

  correct:

  import { SocketIO } 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.

Quickstart

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();