tests.ws

WebSocket Testing Best Practices

websocket testing best-practices automation ci-cd

Testing WebSocket applications requires a fundamentally different mindset than testing traditional HTTP-based APIs. With REST, you send a request and get a response, but WebSocket connections are long-lived, bidirectional, and stateful, which means your tests need to account for message ordering, connection lifecycle events, and asynchronous behavior that simply does not exist in request-response models. If you skip proper WebSocket testing, you will ship bugs around reconnection handling, message parsing, and edge cases that only surface under real-world conditions.

The Test Pyramid for WebSocket Applications

The classic test pyramid still applies to WebSocket apps, but each layer takes on a different character. At the base, unit tests cover your message handlers, serialization logic, and state management in isolation, without any actual network connections. The middle layer consists of integration tests where you spin up a real WebSocket server in your test process, connect to it, and verify end-to-end message flows. At the top, end-to-end tests exercise your full application stack, including the browser or client, the WebSocket server, and any backing services.

For most WebSocket applications, you should aim for roughly 60% unit tests, 30% integration tests, and 10% end-to-end tests. The integration layer is larger here than in typical REST apps because so many bugs hide in the connection lifecycle, and unit tests alone cannot catch them. If you are new to WebSocket testing in general, check out How to Test WebSocket Connections for a beginner-friendly walkthrough.

Unit Testing Message Handlers

The single most important thing you can do for testability is separate your message handling logic from the WebSocket transport layer. If your business logic lives inside ws.on('message', ...) callbacks, every test requires a real or mocked connection. Instead, extract handlers into pure functions.

// handlers.js
function handleChatMessage(payload, context) {
  if (!payload.text || payload.text.trim().length === 0) {
    return { type: 'error', code: 'EMPTY_MESSAGE' };
  }

  if (payload.text.length > 2000) {
    return { type: 'error', code: 'MESSAGE_TOO_LONG' };
  }

  const sanitized = payload.text.trim();

  return {
    type: 'chat:broadcast',
    data: {
      id: context.generateId(),
      userId: context.userId,
      text: sanitized,
      timestamp: context.now(),
    },
  };
}

module.exports = { handleChatMessage };

Now your unit tests are straightforward and fast:

const { handleChatMessage } = require('./handlers');

describe('handleChatMessage', () => {
  const context = {
    userId: 'user-123',
    generateId: () => 'msg-001',
    now: () => 1707753600000,
  };

  test('rejects empty messages', () => {
    const result = handleChatMessage({ text: '' }, context);
    expect(result).toEqual({ type: 'error', code: 'EMPTY_MESSAGE' });
  });

  test('rejects messages over 2000 characters', () => {
    const result = handleChatMessage({ text: 'a'.repeat(2001) }, context);
    expect(result).toEqual({ type: 'error', code: 'MESSAGE_TOO_LONG' });
  });

  test('returns broadcast payload for valid messages', () => {
    const result = handleChatMessage({ text: 'Hello everyone' }, context);
    expect(result.type).toBe('chat:broadcast');
    expect(result.data.text).toBe('Hello everyone');
    expect(result.data.userId).toBe('user-123');
  });
});

These tests run in milliseconds, require no network setup, and cover the core logic. The thin WebSocket layer that wires these handlers to actual connections becomes a simple routing concern that your integration tests cover.

Integration Testing with Real WebSocket Connections

For integration tests, spin up an actual WebSocket server inside your test suite, connect to it with a client, and assert on the messages that flow back and forth. This approach catches issues with serialization, event ordering, and connection setup that unit tests miss entirely.

const { WebSocketServer } = require('ws');
const WebSocket = require('ws');
const { createApp } = require('./app');

describe('WebSocket integration', () => {
  let wss;
  let server;
  let port;

  beforeAll((done) => {
    server = createApp();
    server.listen(0, () => {
      port = server.address().port;
      wss = new WebSocketServer({ server });
      setupHandlers(wss);
      done();
    });
  });

  afterAll((done) => {
    wss.close();
    server.close(done);
  });

  function connectClient() {
    return new Promise((resolve, reject) => {
      const ws = new WebSocket(`ws://localhost:${port}`);
      ws.on('open', () => resolve(ws));
      ws.on('error', reject);
    });
  }

  function waitForMessage(ws) {
    return new Promise((resolve) => {
      ws.once('message', (data) => resolve(JSON.parse(data)));
    });
  }

  test('server sends welcome message on connection', async () => {
    const ws = await connectClient();
    const msg = await waitForMessage(ws);
    expect(msg.type).toBe('welcome');
    expect(msg.data.serverTime).toBeDefined();
    ws.close();
  });

  test('echoes chat messages to all connected clients', async () => {
    const client1 = await connectClient();
    const client2 = await connectClient();

    // Consume welcome messages
    await waitForMessage(client1);
    await waitForMessage(client2);

    const broadcastPromise = waitForMessage(client2);
    client1.send(JSON.stringify({ type: 'chat', text: 'Hello' }));

    const broadcast = await broadcastPromise;
    expect(broadcast.type).toBe('chat:broadcast');
    expect(broadcast.data.text).toBe('Hello');

    client1.close();
    client2.close();
  });
});

A few things to note in this setup. Using port 0 lets the OS assign a random available port, which prevents conflicts when running tests in parallel. The waitForMessage helper turns the event-based API into promises, making tests much easier to read. Always close your connections in the test to avoid resource leaks that cause flaky test runs.

Testing Reconnection Logic

Reconnection handling is one of the most error-prone parts of any WebSocket client. Your tests should verify that the client actually reconnects after a dropped connection, that it applies exponential backoff, and that it restores state after reconnecting.

describe('reconnection', () => {
  test('reconnects with exponential backoff after server disconnect', async () => {
    const delays = [];
    const client = createReconnectingClient(`ws://localhost:${port}`, {
      onReconnectAttempt: (attempt, delay) => delays.push(delay),
      initialDelay: 100,
      maxDelay: 5000,
    });

    await client.waitForConnection();

    // Kill the server to force a disconnect
    wss.close();

    // Wait for a few reconnection attempts
    await sleep(2000);

    expect(delays.length).toBeGreaterThanOrEqual(3);
    expect(delays[0]).toBe(100);
    expect(delays[1]).toBe(200);
    expect(delays[2]).toBe(400);

    client.destroy();
  });

  test('resubscribes to channels after reconnection', async () => {
    const client = createReconnectingClient(`ws://localhost:${port}`);
    await client.waitForConnection();
    client.subscribe('room:general');

    // Simulate server restart
    await restartServer();

    await client.waitForConnection();
    const subscriptions = await getServerSubscriptions(client.id);
    expect(subscriptions).toContain('room:general');

    client.destroy();
  });
});

The second test is critical. Many WebSocket apps maintain subscriptions or authentication state, and all of that needs to be restored after a reconnection. If your client library does not handle this automatically, your application code must do it in the onReconnect callback.

Testing Error Scenarios

Real WebSocket applications encounter server crashes, network interruptions, malformed messages, and protocol violations. Your test suite should exercise each of these scenarios explicitly.

Server Crash Handling

test('client handles abrupt server termination', async () => {
  const client = await connectClient();
  const closePromise = new Promise((resolve) => {
    client.on('close', (code, reason) => resolve({ code, reason: reason.toString() }));
  });

  // Abruptly terminate the server
  server.close();

  const closeEvent = await closePromise;
  expect(closeEvent.code).toBe(1006); // Abnormal closure
});

Invalid Message Handling

test('server handles malformed JSON gracefully', async () => {
  const ws = await connectClient();
  await waitForMessage(ws); // welcome

  const errorPromise = waitForMessage(ws);
  ws.send('this is not valid JSON{{{');

  const error = await errorPromise;
  expect(error.type).toBe('error');
  expect(error.code).toBe('INVALID_JSON');
});

test('server handles unknown message types', async () => {
  const ws = await connectClient();
  await waitForMessage(ws); // welcome

  const errorPromise = waitForMessage(ws);
  ws.send(JSON.stringify({ type: 'nonexistent_action' }));

  const error = await errorPromise;
  expect(error.type).toBe('error');
  expect(error.code).toBe('UNKNOWN_TYPE');
});

You should also test what happens when a client sends messages faster than the server can process them, when a client sends messages during the closing handshake, and when the server sends a close frame with various status codes. For a catalog of WebSocket Testing Tools that can simulate these scenarios, see our tools comparison page.

Testing Binary Messages and Large Payloads

If your application handles binary data (file uploads, audio streams, protocol buffers), you need dedicated tests for binary message handling. You should also verify that your server correctly handles messages at the boundary of your configured maximum payload size.

test('handles binary messages', async () => {
  const ws = await connectClient();
  await waitForMessage(ws);

  const binaryData = Buffer.from([0x00, 0x01, 0x02, 0xFF, 0xFE]);
  const responsePromise = waitForMessage(ws);
  ws.send(binaryData);

  const response = await responsePromise;
  expect(response.type).toBe('binary:received');
  expect(response.data.byteLength).toBe(5);
});

test('rejects payloads exceeding size limit', async () => {
  const ws = await connectClient();
  await waitForMessage(ws);

  const largePayload = JSON.stringify({
    type: 'upload',
    data: 'x'.repeat(5 * 1024 * 1024), // 5MB
  });

  const closePromise = new Promise((resolve) => {
    ws.on('close', (code) => resolve(code));
  });

  ws.send(largePayload);

  const closeCode = await closePromise;
  expect(closeCode).toBe(1009); // Message Too Big
});

Make sure your WebSocket server configuration sets explicit maxPayload limits and that your tests verify both acceptance and rejection at those boundaries.

Testing Authentication Flows

Most production WebSocket applications require authentication. There are two common patterns: authenticating via HTTP headers during the upgrade request, and authenticating via a message after the connection is established. Test both the success and failure cases.

describe('authentication', () => {
  test('rejects connections without a valid token', async () => {
    const ws = new WebSocket(`ws://localhost:${port}`, {
      headers: { Authorization: 'Bearer invalid-token' },
    });

    const closeCode = await new Promise((resolve) => {
      ws.on('close', (code) => resolve(code));
      ws.on('unexpected-response', (req, res) => {
        resolve(res.statusCode);
      });
    });

    expect(closeCode).toBe(401);
  });

  test('accepts connections with a valid token', async () => {
    const token = await generateTestToken({ userId: 'user-456' });
    const ws = new WebSocket(`ws://localhost:${port}`, {
      headers: { Authorization: `Bearer ${token}` },
    });

    const msg = await new Promise((resolve) => {
      ws.on('message', (data) => resolve(JSON.parse(data)));
    });

    expect(msg.type).toBe('welcome');
    expect(msg.data.userId).toBe('user-456');
    ws.close();
  });

  test('disconnects client when token expires mid-session', async () => {
    const token = await generateTestToken({ userId: 'user-789', expiresIn: '2s' });
    const ws = new WebSocket(`ws://localhost:${port}`, {
      headers: { Authorization: `Bearer ${token}` },
    });

    await new Promise((resolve) => ws.on('open', resolve));

    const closeCode = await new Promise((resolve) => {
      ws.on('close', (code) => resolve(code));
    });

    expect(closeCode).toBe(4001); // Custom close code for expired auth
  });
});

The mid-session expiration test is one that many teams overlook. If your server validates tokens periodically or on each message, make sure your tests cover the case where a previously valid token becomes invalid while the connection is still open.

Mocking WebSocket Connections in Frontend Tests

When testing frontend components that depend on WebSocket connections, you do not want to spin up a real server. Instead, mock the WebSocket object to control what messages arrive and verify what messages get sent.

// __mocks__/mockWebSocket.js
class MockWebSocket {
  static instances = [];

  constructor(url) {
    this.url = url;
    this.readyState = WebSocket.CONNECTING;
    this.sentMessages = [];
    this._listeners = {};
    MockWebSocket.instances.push(this);

    setTimeout(() => {
      this.readyState = WebSocket.OPEN;
      this._emit('open', {});
    }, 0);
  }

  send(data) {
    this.sentMessages.push(JSON.parse(data));
  }

  close(code = 1000) {
    this.readyState = WebSocket.CLOSED;
    this._emit('close', { code });
  }

  addEventListener(event, fn) {
    if (!this._listeners[event]) this._listeners[event] = [];
    this._listeners[event].push(fn);
  }

  removeEventListener(event, fn) {
    if (this._listeners[event]) {
      this._listeners[event] = this._listeners[event].filter((f) => f !== fn);
    }
  }

  _emit(event, data) {
    (this._listeners[event] || []).forEach((fn) => fn(data));
  }

  simulateMessage(payload) {
    this._emit('message', { data: JSON.stringify(payload) });
  }
}

Then in your React or framework tests:

import { render, screen, waitFor } from '@testing-library/react';
import { ChatRoom } from './ChatRoom';

beforeEach(() => {
  global.WebSocket = MockWebSocket;
  MockWebSocket.instances = [];
});

test('displays incoming chat messages', async () => {
  render(<ChatRoom roomId="general" />);

  const ws = MockWebSocket.instances[0];
  ws.simulateMessage({ type: 'chat:broadcast', data: { text: 'Hi there', userId: 'alice' } });

  await waitFor(() => {
    expect(screen.getByText('Hi there')).toBeInTheDocument();
  });
});

test('sends message when user submits form', async () => {
  render(<ChatRoom roomId="general" />);

  const input = screen.getByRole('textbox');
  const button = screen.getByRole('button', { name: /send/i });

  fireEvent.change(input, { target: { value: 'Hello world' } });
  fireEvent.click(button);

  const ws = MockWebSocket.instances[0];
  expect(ws.sentMessages).toContainEqual({
    type: 'chat',
    roomId: 'general',
    text: 'Hello world',
  });
});

This mock approach keeps frontend tests fast and deterministic. You control exactly when messages arrive, which eliminates timing-related flakiness. For more strategies on testing WebSocket clients in the browser, see Load Testing WebSocket for performance-focused testing.

CI Pipeline Setup with GitHub Actions

WebSocket tests need a running server, which adds complexity to your CI configuration. Here is a GitHub Actions workflow that runs both unit and integration tests:

name: WebSocket Tests
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'

      - run: npm ci

      - name: Run unit tests
        run: npm run test:unit -- --coverage

      - name: Run integration tests
        run: npm run test:integration
        timeout-minutes: 5

      - name: Run e2e WebSocket tests
        run: |
          npm run start:test-server &
          SERVER_PID=$!
          sleep 3
          npm run test:e2e
          kill $SERVER_PID

      - name: Upload coverage
        uses: codecov/codecov-action@v4
        with:
          files: ./coverage/lcov.info

A few important details. The timeout-minutes on integration tests prevents hung connections from blocking your pipeline indefinitely. For e2e tests, you start the server as a background process, wait for it to be ready, run the tests, and then clean up. In production CI setups, replace sleep 3 with a proper health check loop:

for i in $(seq 1 30); do
  curl -s http://localhost:3000/health && break
  sleep 1
done

If your WebSocket tests are flaky in CI but pass locally, the most common causes are: port conflicts (use random ports), timing assumptions (increase timeouts in CI), and missing cleanup (always close connections in afterEach).

Code Coverage for WebSocket Handlers

Measuring code coverage for WebSocket handlers requires some extra attention because standard coverage tools track line execution, not protocol-level coverage. You might have 100% line coverage but never test what happens when a client disconnects during a message broadcast.

Add these categories to your coverage checklist beyond line coverage:

  • Connection lifecycle: open, close (clean), close (abnormal), error events
  • Message types: every message type your server handles, plus unknown types
  • State transitions: every state your connection can be in (authenticated, subscribed, idle, rate-limited)
  • Error paths: invalid JSON, schema violations, authorization failures, rate limit exceeded

Configure Istanbul or c8 in your project to generate coverage reports, and set minimum thresholds in your CI pipeline:

{
  "c8": {
    "check-coverage": true,
    "lines": 85,
    "functions": 85,
    "branches": 80,
    "reporter": ["text", "lcov"]
  }
}

WebSocket Testing Checklist

Before shipping any WebSocket feature, run through this checklist. Print it out, pin it to your wall, or add it to your pull request template.

Connection Lifecycle

  • Client connects successfully and receives a welcome/acknowledgment message
  • Client receives proper close codes on server-initiated disconnect
  • Client handles server being unavailable at connection time
  • Client reconnects automatically after unexpected disconnection
  • Client applies exponential backoff on reconnection attempts
  • Client restores subscriptions and state after reconnection

Message Handling

  • All defined message types are handled correctly
  • Unknown message types return an error, not crash the server
  • Malformed JSON is rejected gracefully
  • Messages exceeding size limits are rejected with code 1009
  • Binary messages are processed correctly (if applicable)
  • Message ordering is preserved within a single connection

Security

  • Unauthenticated connections are rejected
  • Expired tokens cause disconnection with an appropriate close code
  • Rate limiting prevents message flooding
  • Input validation prevents injection attacks in message payloads

Performance

  • Server handles the expected number of concurrent connections
  • Message throughput meets requirements under load
  • Memory does not leak over long-lived connections
  • Heartbeat/ping-pong keeps connections alive through proxies

For deeper performance validation, see our guide on Load Testing WebSocket.

Frequently Asked Questions

How do I prevent WebSocket tests from being flaky?

Flaky WebSocket tests almost always come from timing issues. Never use fixed setTimeout delays to wait for messages. Instead, use promise-based helpers that resolve when a specific message arrives, with a timeout that fails the test if the message never comes. Close all connections in afterEach hooks, and use random ports to avoid conflicts when tests run in parallel. If you are still seeing intermittent failures, add logging to your test server to see exactly what messages were sent and received, and in what order.

Should I use a WebSocket testing library or write my own helpers?

For most projects, writing a small set of helpers (like the connectClient and waitForMessage functions shown earlier) gives you enough control without adding a dependency. If you need advanced features like protocol-level assertions, automatic reconnection testing, or load generation, consider dedicated tools. Check WebSocket Testing Tools for a comparison of available options. The key is to keep your test utilities thin so that when the underlying WebSocket library changes, you only update the helpers, not every test file.

How do I test WebSocket connections through a load balancer or proxy?

If your production setup includes a reverse proxy like Nginx or a load balancer, your e2e tests should run through that same infrastructure. Use Docker Compose to spin up the full stack in CI, including the proxy layer. Test that WebSocket upgrade requests pass through correctly, that sticky sessions work if you have multiple server instances, and that the proxy’s idle timeout does not kill connections prematurely. Also verify that your ping/pong mechanism keeps connections alive through the proxy’s timeout window.

What close codes should I test for?

At minimum, test for these close codes: 1000 (normal closure), 1001 (going away, used when server shuts down), 1006 (abnormal closure, no close frame received), 1008 (policy violation, good for auth failures), 1009 (message too big), and 1011 (unexpected condition). If your application defines custom close codes in the 4000-4999 range, test each of those as well. Your client should handle every code gracefully, even codes it does not specifically recognize, by falling back to a generic disconnection handler.