mocket.io-client

A Vitest mocking library for testing socket.io-client integrations without requiring actual server connections.

Installation

npm install --save-dev @xikww/mocket.io-client

Create a setup file for vitest (or use an existing one) with this:

// e.g. a new file "vitest.mocketio-setup.ts"
import { mockSocketioClient } from "@xikww/mocket.io-client/setup";

mockSocketioClient();

Then, simply update your vitest.config to include the setup file:

export default defineConfig({
  test: {
    setupFiles: [
      ...,
      "./vitest.mocketio-setup.ts"
    ],
  },
});

Usage

This library exports a single function (two aliases) — a custom Vitest Test Context. In any of your test files, do:

import { vi } from "vitest";
import { io } from "socket.io-client";
import { _itWithMocketioClient } from "@xikww/mocket.io-client/context";

const itWithMocketioClient = _itWithMocketioClient(vi.mocked(io));

Now the custom context can be used. For any test wrapped within this context:

itWithMocketioClient("your test", ({ mocketio } => {
  // 1. The `socket.io-client` API is, at this point, already mocked behind the scenes
  // 2. A fixture `mocketio` is available (see the API reference below)
}));

Examples

Basic server-driven connection/disconnection:

import { io } from "socket.io-client";
import { describe, expect, vi } from "vitest";
import { _itWithMocketioClient } from "@xikww/mocket.io-client/context";

const itWithMocketioClient = _itWithMocketioClient(vi.mocked(io));

describe("my tests", () => {
  itWithMocketioClient("handles connect/disconnect", ({ mocketio }) => {
    // Instantiate your regular object that calls `io(...)`
    chatClient = new ChatRoomClient("http://localhost:9999");

    // Simulate a "connect" event coming from the server
    mocketio.server.mockEmit("connect");

    // Magically works!
    expect(chatClient.isConnected).toBe(true);

    // Simulate a "disconnect" event coming from the server
    mocketio.server.mockEmit("disconnect");

    // Magically works!
    expect(chatClient.isConnected).toBe(false);
    expect(chatClient.currentRoom).toBe("");
    expect(chatClient.users).toEqual([]);
  });
});

Mock server-side handling (e.g. for testing client emissions and server acks):

import { io } from "socket.io-client";
import { describe, expect, vi } from "vitest";
import { _itWithMocketioClient } from "@xikww/mocket.io-client/context";

const itWithMocketioClient = _itWithMocketioClient(vi.mocked(io));

describe("my tests", () => {
  itWithMocketioClient("mock server handler", async ({ mocketio }) => {
    // Instantiate your regular object that calls `io(...)`
    chatClient = new ChatRoomClient("http://localhost:9999");

    // Simulate a "connect" event coming from the server
    mocketio.server.mockEmit("connect");
    expect(chatClient.isConnected).toBe(true);

    // Mock the server-side handler to assert that the payload sent from the
    // client is in the expected format +  acknowledge the client-emitted event
    mocketio.server.mockOn("joinRoom", (username, room, callback) => {
      expect(room).toBe("general");
      callback(true);
    });

    await chatClient.joinRoom("testuser", "general");

    // Simulate other users joining
    mocketioClient.server.mockEmit("userJoined", "user2", 2);
    mocketioClient.server.mockEmit("userJoined", "user3", 3);

    // Should have both other users (not including self)
    expect(chatClient.users).toContain("user2");
    expect(chatClient.users).toContain("user3");
    expect(chatClient.users).toHaveLength(2);
  });
});

For more examples, please check the examples folder.

API Reference

The mocketio fixture that you can use within your tests has two fields, client and server.

Client API

The goal of this library is to help you seamlessly test your client-side socket.io features — behind the scenes, it already mocks the actual public-facing API of socket.io-client in a way that allows for fast, reliable testing. This means that, for the vast majority of cases, you shouldn't need to use the client API that the mocketio fixture provides. For this reason, the API is minimal to allow for edge cases:

• client.getAttribute(key) - Get the values of an attribute by key.
• client.getAttributes() - Get the values of all attributes.
• client.mockAttribute(key, value) - Manually set the value for an attribute.
• client.mockOpen() - Manually trigger a connection.
• client.mockClose() - Manually trigger a disconnection.
• client.mockConnect() - Alias for mockOpen.
• client.mockDisconnect() - Alias for mockClose.

Server API

For client-side integration testing purposes, the server should be a black box; the server API provided by the mocketio fixture gives us just enough so that we can mock server emissions and event handlers to tailor the client's needs:

• server.mockEmit(eventName, ...args) - Simulate an event emission from the server.
• server.mockOn(eventName, ...args) - Mock a server-side ad-hoc handler for any event.

Contributing

$ clone this repo && cd /to/it
$ pnpm install
$ pnpm build

For testing, you can run the following commands:

$ pnpm test // run all tests
$ pnpm test:lib // run the lib tests
$ pnpm test:examples // run the tests in the examples folder

This project uses changesets for changelog management:

pnpm changeset add

License

Distributed under the terms of the MIT license, "mocked.io-client" is free and open source software.