Test GraphQL Subscriptions over WebSockets

TL;DR

Start a real graphql-ws server on an ephemeral port, connect with the graphql-ws client, subscribe before publishing, and assert the full result envelope. Add separate tests for variables, authentication, GraphQL errors, unsubscribe behavior, and resource cleanup.

Key Takeaways

• Test subscriptions through a real WebSocket server instead of calling resolvers directly.
• Create the subscriber before triggering the event so the test cannot miss the first payload.
• Assert the GraphQL envelope, payload values, ordering, and absence of unwanted events.
• Pass authentication through connectionParams and reject unauthorized sockets during connection setup.
• Dispose every client and close every server so the test process exits cleanly.
• Use bounded waits and explicit failure messages to diagnose asynchronous failures quickly.

This test graphql subscriptions websockets tutorial shows you how to verify live GraphQL events through a real WebSocket connection. You will create a small subscription server, drive it with a client, and assert delivery, filtering, authentication, errors, and cancellation.

Subscriptions add connection state, asynchronous timing, and cleanup concerns that ordinary query tests do not cover. Use this tutorial as the focused implementation companion to the Modern GraphQL API Testing Complete Guide, which explains the wider test strategy for schemas, queries, mutations, security, and operations.

The examples use TypeScript, Vitest, graphql, graphql-ws, and ws. They exercise the graphql-transport-ws protocol through public library APIs, so you test behavior at the transport boundary rather than proving only that a resolver function returns a value.

What You Will Build

You will build a self-contained integration test project that can:

• start a GraphQL WebSocket server on an available local port;
• subscribe to a messageAdded(roomId: ID!) field;
• publish messages and verify variable-based filtering and event order;
• authenticate a connection with connectionParams;
• assert GraphQL validation errors and unsubscribe behavior;
• release sockets, timers, and servers after every test run.

The final test suite uses no arbitrary sleeps for successful event delivery. A small timeout acts only as a failure boundary or as a deliberate observation window when proving that an event does not arrive.

Prerequisites

Use Node.js 22 or newer and npm 10 or newer. The commands below pin a reproducible baseline: typescript@5.8.3, vitest@3.2.4, graphql@16.11.0, graphql-ws@6.0.6, ws@8.18.3, and @types/ws@8.18.1. If your repository already uses compatible newer releases, keep one lockfile and let your normal dependency review process validate the upgrade.

mkdir graphql-subscription-tests
cd graphql-subscription-tests
npm init -y
npm install graphql@16.11.0 graphql-ws@6.0.6 ws@8.18.3
npm install --save-dev typescript@5.8.3 vitest@3.2.4 @types/node@22.15.30 @types/ws@8.18.1

You need basic familiarity with GraphQL operations, async iterators, and test assertions. You do not need a browser because the Node client receives a WebSocket implementation explicitly.

Verify the prerequisites: run node --version, npm --version, and npm ls graphql graphql-ws ws vitest. Confirm Node reports 22 or later and npm lists one resolved version for each package.

Step 1: Configure TypeScript and the Test Runner

Create the scripts and TypeScript configuration first. Vitest discovers files ending in .test.ts, and the Node environment allows the suite to open a local TCP port.

Update the scripts property in package.json:

{
  "scripts": {
    "test": "vitest run",
    "test:watch": "vitest"
  }
}

Create tsconfig.json:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "Bundler",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "types": ["node", "vitest/globals"]
  },
  "include": ["src/**/*.ts"]
}

Create vitest.config.ts:

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    environment: 'node',
    include: ['src/**/*.test.ts'],
    testTimeout: 5_000,
    hookTimeout: 5_000,
  },
});

Short timeouts are useful here. They convert a missing event or leaked connection into a quick, attributable failure instead of a hung CI job. Do not reduce them so far that normal shared runners become flaky.

Verify Step 1: run npx tsc --noEmit. It should exit with code 0. Run npm test; Vitest should report that no test files were found, which is expected before you add the suite.

Step 2: Build a Minimal Subscription Schema

Create src/schema.ts. This module implements a small async pub/sub bus without a broker dependency.

import { EventEmitter, on } from 'node:events';
import { buildSchema } from 'graphql';

export type Message = { id: string; roomId: string; text: string };
export type Context = { userId: string | null };

export const schema = buildSchema(`
  type Message {
    id: ID!
    roomId: ID!
    text: String!
  }

  type Query {
    health: String!
  }

  type Subscription {
    messageAdded(roomId: ID!): Message!
  }
`);

const bus = new EventEmitter();

export function publishMessage(message: Message): void {
  bus.emit('message', message);
}

async function* messagesForRoom(roomId: string) {
  for await (const [message] of on(bus, 'message')) {
    const typedMessage = message as Message;
    if (typedMessage.roomId === roomId) {
      yield { messageAdded: typedMessage };
    }
  }
}

export const roots = {
  health: () => 'ok',
  messageAdded: (args: { roomId: string }, context: Context) => {
    if (!context.userId) {
      throw new Error('Unauthenticated');
    }
    return messagesForRoom(args.roomId);
  },
};

The subscription root returns an async iterable. Each yielded object matches the GraphQL field name, which allows GraphQL's default field resolver to produce the requested selection. EventEmitter.on also removes its listener when the iterator is returned, so cancellation is observable.

Verify Step 2: run npx tsc --noEmit. Expect no type errors. At this point there is no network listener yet, so do not expect publishMessage alone to print output.

Step 3: Start a Real GraphQL WebSocket Server

Create src/testServer.ts. The server listens on port 0, which asks the operating system for an available port and prevents parallel CI workers from fighting over a hard-coded port.

import { createServer } from 'node:http';
import { WebSocketServer } from 'ws';
import { useServer } from 'graphql-ws/use/ws';
import { roots, schema, type Context } from './schema';

type Params = { authorization?: string };

export async function startTestServer() {
  const httpServer = createServer();
  const wsServer = new WebSocketServer({
    server: httpServer,
    path: '/graphql',
  });

  const cleanup = useServer(
    {
      schema,
      roots,
      context: (ctx): Context => {
        const params = (ctx.connectionParams ?? {}) as Params;
        return {
          userId: params.authorization === 'Bearer test-token'
            ? 'user-123'
            : null,
        };
      },
    },
    wsServer,
  );

  await new Promise<void>((resolve) => httpServer.listen(0, '127.0.0.1', resolve));
  const address = httpServer.address();
  if (!address || typeof address === 'string') throw new Error('No TCP address');

  return {
    url: `ws://127.0.0.1:${address.port}/graphql`,
    async close() {
      await cleanup.dispose();
      await new Promise<void>((resolve, reject) => {
        httpServer.close((error) => error ? reject(error) : resolve());
      });
    },
  };
}

useServer connects GraphQL execution to the ws server. connectionParams is application data sent in the protocol's connection initialization message. The example maps a known bearer token to a test identity and lets the resolver produce a normal GraphQL error for anonymous subscribers.

The roots option supplies the root resolver object required by buildSchema. The library parses and validates each incoming operation before it starts the async iterator.

Verify Step 3: run npx tsc --noEmit again. Expect exit code 0. If TypeScript reports an export-path error, confirm you imported useServer from graphql-ws/use/ws, not an obsolete package path from an older tutorial.

Step 4: Create a Promise-Based Subscription Helper

The client API intentionally exposes a sink with next, error, and complete callbacks. Wrap that API carefully so each test can await one result and always cancel afterward. Create src/subscribeOnce.ts:

import type { Client, ExecutionResult } from 'graphql-ws';

export function subscribeOnce<T>(
  client: Client,
  payload: Parameters<Client['subscribe']>[0],
  timeoutMs = 2_000,
): Promise<ExecutionResult<T>> {
  return new Promise((resolve, reject) => {
    const timer = setTimeout(() => {
      dispose();
      reject(new Error(`No subscription result within ${timeoutMs}ms`));
    }, timeoutMs);

    const finish = (action: () => void) => {
      clearTimeout(timer);
      dispose();
      action();
    };

    const dispose = client.subscribe<T>(payload, {
      next: (result) => finish(() => resolve(result)),
      error: (error) => finish(() => reject(error)),
      complete: () => finish(() => reject(new Error('Completed without a result'))),
    });
  });
}

Calling the returned disposer sends a protocol completion message and stops the operation. The timeout is a ceiling, not a synchronization technique. A successful test resolves as soon as the server emits a result.

Notice that dispose is referenced by callbacks created before its assignment. That is safe because graphql-ws schedules subscription work asynchronously, after client.subscribe returns its disposer.

Verify Step 4: run npx tsc --noEmit. Expect no errors. If a lint rule dislikes the closure ordering, declare let dispose = () => {}; before the timer and assign it when subscribing.

Step 5: Test GraphQL Subscriptions over WebSockets Tutorial Happy Path

Create src/subscriptions.test.ts with lifecycle hooks and the first delivery test:

import { afterEach, beforeEach, describe, expect, it } from 'vitest';
import { createClient, type Client } from 'graphql-ws';
import WebSocket from 'ws';
import { publishMessage } from './schema';
import { subscribeOnce } from './subscribeOnce';
import { startTestServer } from './testServer';

type Server = Awaited<ReturnType<typeof startTestServer>>;
type Payload = {
  messageAdded: { id: string; roomId: string; text: string };
};

describe('messageAdded subscription', () => {
  let server: Server;
  let client: Client;

  beforeEach(async () => {
    server = await startTestServer();
    client = createClient({
      url: server.url,
      webSocketImpl: WebSocket,
      connectionParams: { authorization: 'Bearer test-token' },
      retryAttempts: 0,
    });
  });

  afterEach(async () => {
    await client.dispose();
    await server.close();
  });

  it('delivers a matching message', async () => {
    const resultPromise = subscribeOnce<Payload>(client, {
      query: `
        subscription MessageAdded($roomId: ID!) {
          messageAdded(roomId: $roomId) { id roomId text }
        }
      `,
      variables: { roomId: 'room-a' },
    });

    await new Promise<void>((resolve, reject) => {
      const unsubscribe = client.on('connected', () => {
        unsubscribe();
        resolve();
      });
      setTimeout(() => reject(new Error('Client did not connect')), 1_000);
    });

    publishMessage({ id: 'm1', roomId: 'room-a', text: 'Hello' });

    await expect(resultPromise).resolves.toEqual({
      data: {
        messageAdded: { id: 'm1', roomId: 'room-a', text: 'Hello' },
      },
    });
  });
});

The subscriber is created before the publisher runs. Waiting for the connected event prevents the classic race where an event is emitted before the server has registered the subscription.

Assert the full GraphQL response envelope. A check against only text could miss unexpected errors, nullability problems, or a malformed field structure.

Verify Step 5: run npm test. Expect one passing test and a clean process exit. Repeat with npm test -- --repeat=10 if your Vitest release supports the option, or run the command repeatedly in CI, to expose timing assumptions.

Step 6: Verify Variables, Filtering, and Event Order

A useful subscription test proves that the server excludes unrelated events, not just that one desired event eventually appears. Add this test inside the same describe block. It collects two matching results while publishing an interleaved event for another room.

it('filters by room and preserves matching event order', async () => {
  const received: Payload[] = [];

  const completed = new Promise<void>((resolve, reject) => {
    const dispose = client.subscribe<Payload>(
      {
        query: `
          subscription ($roomId: ID!) {
            messageAdded(roomId: $roomId) { id roomId text }
          }
        `,
        variables: { roomId: 'room-a' },
      },
      {
        next: (result) => {
          if (result.data) received.push(result.data);
          if (received.length === 2) {
            dispose();
            resolve();
          }
        },
        error: reject,
        complete: () => {},
      },
    );
    setTimeout(() => reject(new Error('Expected two matching events')), 2_000);
  });

  await new Promise<void>((resolve) => {
    const off = client.on('connected', () => { off(); resolve(); });
  });

  publishMessage({ id: 'm1', roomId: 'room-a', text: 'First' });
  publishMessage({ id: 'x1', roomId: 'room-b', text: 'Ignore' });
  publishMessage({ id: 'm2', roomId: 'room-a', text: 'Second' });

  await completed;
  expect(received.map((item) => item.messageAdded.id)).toEqual(['m1', 'm2']);
  expect(received.every((item) => item.messageAdded.roomId === 'room-a')).toBe(true);
});

This assertion covers variable transport, resolver filtering, and ordering for the in-process event source. Do not generalize it into a guarantee that every distributed broker preserves global order. State the ordering contract your application promises.

Verify Step 6: run npm test. Expect two passing tests.

Step 7: Test Authentication and GraphQL Errors

Transport success is not application authorization. A socket can connect successfully and still receive an execution error for a protected subscription. Add a test that creates an anonymous client and checks the error result.

it('returns a GraphQL error to an unauthenticated subscriber', async () => {
  const anonymous = createClient({
    url: server.url,
    webSocketImpl: WebSocket,
    retryAttempts: 0,
  });

  try {
    const result = await subscribeOnce<Payload>(anonymous, {
      query: `
        subscription {
          messageAdded(roomId: "room-a") { id }
        }
      `,
    });

    expect(result.data).toBeUndefined();
    expect(result.errors?.[0]?.message).toBe('Unauthenticated');
  } finally {
    await anonymous.dispose();
  }
});

it('reports an invalid subscription field', async () => {
  const result = await subscribeOnce(client, {
    query: `subscription { unknownEvent }`,
  });

  expect(result.data).toBeUndefined();
  expect(result.errors?.[0]?.message).toContain('Cannot query field');
});

These are two different negative paths. The first operation is valid but unauthorized during subscription resolution. The second fails GraphQL validation before an event stream starts. Assert stable semantics, such as the presence of an error and an application error code when your server provides one. Avoid snapshots of entire error objects because locations, stack details, or wording can change across GraphQL releases.

For APIs that reject the entire connection, implement authentication in the server's connection hook and test the documented WebSocket close code. Resolver-level rejection is appropriate here because it keeps transport and field authorization concerns separate.

Verify Step 7: run npm test. Expect four passing tests. Change the token to an invalid value in beforeEach; the happy-path tests should fail with Unauthenticated, proving the credentials are exercised. Restore the token afterward.

Step 8: Prove Unsubscribe and Cleanup Behavior

Cancellation deserves its own test because leaked iterators consume memory and may continue work after a user leaves a page. Export a diagnostic listener count from src/schema.ts:

export function activeMessageListeners(): number {
  return bus.listenerCount('message');
}

Then import it beside publishMessage and add this test:

it('removes the event listener after unsubscribe', async () => {
  const dispose = client.subscribe<Payload>(
    {
      query: `
        subscription {
          messageAdded(roomId: "room-a") { id }
        }
      `,
    },
    { next: () => {}, error: () => {}, complete: () => {} },
  );

  await expect.poll(() => activeMessageListeners()).toBe(1);
  dispose();
  await expect.poll(() => activeMessageListeners()).toBe(0);
});

expect.poll repeatedly evaluates the condition within Vitest's timeout. That is better than sleeping for a guessed number of milliseconds. The count is a test seam. In production, verify an equivalent observable contract, such as a broker consumer count, cancellation callback, or absence of post-cancel side effects.

Cleanup order matters. Dispose clients first so operations complete while the server can still process protocol messages. Then dispose the GraphQL server integration and close the HTTP server. If a failure occurs halfway through a test, afterEach still executes.

Verify Step 8: run npm test. Expect five passing tests and no message about open handles. Run the suite several times. The listener count must return to zero after every cancellation, and the command must return to your shell without waiting for the test timeout.

GraphQL WebSocket Testing Strategy

Choose the test layer based on the risk you need to cover. A resolver unit test is fast, but it cannot prove protocol negotiation, variables, serialization, connection authentication, or cancellation. A browser end-to-end test covers the whole product, but it is slower and makes transport failures harder to isolate.

Keep most cases at the in-process integration layer built here. Add a small deployed smoke suite for wss:// routing, gateway idle timeouts, and real identity tokens. Retain one or two browser flows for visible updates. This distribution gives fast feedback without pretending that a local socket reproduces every production intermediary.

For broader API risks, pair subscriptions with GraphQL query complexity and security testing. Subscriptions can hold server resources for a long time, so depth limits, per-user operation limits, payload validation, and rate controls still matter.

Troubleshooting

Problem: the test times out before receiving the first event -> Create the subscription first and wait for the client's connected event before publishing. Also confirm the URL includes the exact /graphql path and the server and client both use graphql-transport-ws.

Problem: the server returns Unauthenticated with a valid-looking token -> Inspect the shape and timing of connectionParams. In this tutorial it must be { authorization: 'Bearer test-token' }; HTTP headers configured on a query client are not automatically copied to a WebSocket connection.

Problem: Vitest finishes assertions but does not exit -> Dispose every client in finally or afterEach, call the disposer returned by each subscription, dispose useServer, and close the HTTP server. Look for retry timers if retryAttempts is greater than zero.

Problem: events occasionally disappear in CI -> Remove publish-before-subscribe races. Do not fix them by adding a longer sleep. Wait on a readiness signal, use an application acknowledgement, or publish only after the server confirms the operation is active.

Problem: validation errors arrive in next instead of the sink's error callback -> That is expected for GraphQL execution results. The sink error callback represents protocol or transport failure, while GraphQL errors normally appear in the result envelope's errors array.

Problem: a reverse proxy works for queries but not subscriptions -> Verify WebSocket upgrade forwarding, the wss:// scheme, path routing, origin policy, idle timeout, and subprotocol forwarding. Reproduce with a deployed integration test before debugging the UI.

Best Practices

• Subscribe before triggering the action that publishes an event.
• Use an ephemeral port for local tests and unique tenant, user, or room identifiers in shared environments.
• Disable automatic retries in deterministic integration tests, then test retry policy separately.
• Assert data, errors, ordering, filtering, and the absence of forbidden fields.
• Put a bounded timeout around every asynchronous wait and include the unmet condition in the message.
• Cancel subscriptions in finally blocks and close clients before servers.
• Test authorization at connection and field levels according to the API contract.
• Avoid brittle assertions against entire error strings or internal close reasons.
• Never use production tokens, real customer channels, or shared production events in automated tests.

Schema evolution can break long-lived operations even when a short query test passes. Add GraphQL deprecation validation with schema diff to CI so removed fields and changed arguments are detected before subscription clients fail. If your clients combine operations for throughput, also test GraphQL batched request behavior and examples, while remembering that WebSocket subscription multiplexing is protocol-level operation sharing, not HTTP request batching.

Where To Go Next

You now have the core of a reliable subscription regression suite. Apply these next steps in order:

1. Return to the complete modern GraphQL API testing guide and map subscription tests into the full test pyramid.
2. Add GraphQL query complexity security tests for expensive or abusive subscription documents.
3. Add schema diff checks for GraphQL deprecations before removing subscription fields or payload properties.
4. Test a deployed wss:// endpoint through your real gateway, identity provider, and broker.
5. Measure connection count, event lag, delivery errors, cancellation, and reconnects with production-safe observability.

Keep the local suite deterministic. Test reconnect and broker recovery in isolated cases where you can control server shutdown and event identity. When delivery can be repeated, attach an event ID and assert the client's documented deduplication behavior rather than assuming exactly-once delivery.

Interview Questions and Answers

Q: Why should you test a GraphQL subscription through a real WebSocket?

A real connection covers subprotocol negotiation, initialization, variables, serialization, asynchronous results, cancellation, and close behavior. Calling the resolver directly covers business logic but misses those transport risks. Use both layers for different feedback.

Q: How do you prevent a publish-before-subscribe race?

Create the subscription before publishing and wait for an observable readiness signal. A client connection event is enough for this small fixture, while a production harness may need an operation acknowledgement or server-side subscription hook. Arbitrary sleeps only hide the race.

Q: What is the difference between a GraphQL error and a WebSocket error?

A GraphQL validation or execution error normally arrives in an ExecutionResult.errors array. A network failure, protocol violation, or abnormal close is a transport concern and reaches the sink error path or close event. Tests should assert the correct channel.

Q: How do you test subscription authentication?

Send credentials in connectionParams, then test valid, missing, expired, and unauthorized identities. Assert whether the contract rejects the connection or returns a field-level GraphQL error. Do not assume HTTP client headers automatically apply to WebSockets.

Q: Why disable retries in most integration tests?

Retries can mask the first failure and create background timers that outlive the assertion. Set retry attempts to zero for deterministic functional cases. Write a separate test with controlled disconnects when reconnect behavior itself is the requirement.

Q: How do you verify cleanup?

Call the operation disposer, dispose the client, and close the server. Observe a meaningful signal such as listener count, broker consumers, or post-cancel side effects. The test runner must exit without open-handle warnings.

Conclusion

To test GraphQL subscriptions reliably, exercise a real WebSocket boundary, establish the subscriber before publishing, assert the complete result, and clean up every operation. The runnable suite in this tutorial covers delivery, variables, filtering, authentication, validation errors, ordering, and cancellation without depending on fragile success-path sleeps.

Run the suite locally, then adapt the same contracts to a deployed wss:// smoke test. Keep resolver unit tests for business-rule breadth and use a small number of browser tests for the user-visible live experience.

Interview Questions and Answers

Frequently Asked Questions

Related Guides

• Testing GraphQL subscriptions (2026)
• Selenium Test Web Components Slots Tutorial: Test Web Component Slots with Selenium
• Test Batched GraphQL Requests with Examples
• Test scenarios vs test cases (2026)
• TypeScript Decorators Test Metadata Tutorial: Create Test Metadata
• A/B test validation: A Complete Guide for QA (2026)