smocket mascot: a cool cat wearing sunglassessmocket

Mock Socket.IO without a server.

smocket runs Socket.IO rooms, broadcasts, and acknowledgements in memory. Supported behaviour is checked against the real library.

  • v1.0.1
a s’more rocket blasting off
Each message reaches exactly the sockets it was addressed to, and no others.

Three players without a backend server.

Draw and guess in one tab with scripted players, or play across browser tabs. Smocket routes the events in your browser without a Socket.IO backend.

A recorded round, replayed.Take the pen

Use your Socket.IO handlers without starting a network server.

Node.js Socket.IO mock serverHTTP server, listening port, and cleanup.ABC
import { once } from 'node:events';
import { createServer } from 'node:http';
import type { AddressInfo } from 'node:net';
import { Server } from 'socket.io';
import { io as connect } from 'socket.io-client';

const httpServer = createServer();
const io = new Server(httpServer);
registerApplication(io);

httpServer.listen(0, '127.0.0.1');
await once(httpServer, 'listening');

const { port } = httpServer.address() as AddressInfo;
const url = `http://127.0.0.1:${port}`;
const a = connect(url);
const b = connect(url);
const c = connect(url);

// Then disconnect every client, close Socket.IO,
// and close the HTTP server after the test.
smocketThe same handlers, no listening server.ABC
import { Server } from 'smocket';
import { connect } from 'smocket-client';

const url = 'http://localhost:3000';
const io = new Server(url);
registerApplication(io);

const a = connect(url);
const b = connect(url);
const c = connect(url);

registerApplication(io) stays the same.

Built around Socket.IO behavior.

  • Delivery fidelity

    Room membership and socket ids determine who receives an event. Room unions and exclusions select each recipient once.

  • Checked against the real thing

    The same conformance cases run against Socket.IO and smocket. Browser, SharedWorker, and package checks cover behaviour specific to smocket.

  • No server, no ports

    The mock runs without a network server or a listening port. Use it in tests, in a browser page, or in a SharedWorker shared by browser tabs.

  • Honest about its limits

    Supported behaviour, deliberate differences, and transport features outside its scope are documented.

Switch in three steps.

  1. Install

    npm install -D smocket smocket-client
  2. Alias the client

    // vitest.config.ts
    import { defineConfig } from 'vitest/config';
    
    export default defineConfig({
      resolve: {
        alias: { 'socket.io-client': 'smocket-client' },
      },
    });
  3. Run your app code

    import { expect, it } from 'vitest';
    import { Server, type ServerSocketContract } from 'smocket';
    import { joinChat } from '../src/chat';
    
    it('delivers a room message to the other member', async () => {
      const url = 'http://localhost:3000';
      const io = new Server(url);
    
      io.on('connection', (socket: ServerSocketContract) => {
        socket.on('join', async (room: string, ack: () => void) => {
          await socket.join(room);
          ack();
          socket.on('message', (text: string) => {
            socket.to(room).emit('message', text);
          });
        });
      });
    
      try {
        // joinChat still imports io from socket.io-client.
        const a = joinChat(url, 'alice', 'general');
        const b = joinChat(url, 'bob', 'general');
        await Promise.all([a.ready, b.ready]);
    
        const heard = new Promise((resolve) => b.onMessage(resolve));
        a.send('hello');
    
        await expect(heard).resolves.toBe('hello');
      } finally {
        await io.close();
      }
    });

See who received what.

Rooms, exclusions, and targeted emits follow the supported delivery semantics verified against Socket.IO. Here is the delivery record.

  • A
  • B
  • C
socket_A.to('room-1').emit('stroke', { … })
B, C (except A)
io.to(sid_A).emit('word', 'giraffe')
A
io.to('room-1').emit('chat', { … })
A, B, C

Scope

What smocket does

  • Rooms and namespaces
  • Broadcast, with and without exclusions
  • Targeted emits by socket id
  • Acknowledgements, including timeouts
  • Middleware, handshake, and data stored on each socket
  • Disconnect cleanup

What smocket does not reproduce

  • Automatic reconnection after network failures
  • Fallback between WebSocket and HTTP long polling
  • Network heartbeat and connection health checks
  • Scaling across servers with adapters such as Redis
  • Binary protocol encoding and network framing
0%