GraphQL Server Testing with SuperTest

Common errors

• TypeError: Schema must be an instance of GraphQLSchema.

  cause The GraphQL server was initialized with an invalid schema object, or the schema was not correctly built before being passed to the server.
  fix Ensure your `typeDefs` and `resolvers` are correctly defined and processed by your GraphQL server library (e.g., `makeExecutableSchema` from `@graphql-tools/schema` or `new ApolloServer({ typeDefs, resolvers })`). Double-check imports for `GraphQLSchema`.

• Error: socket hang up (or similar network error like ECONNREFUSED)

  cause The HTTP server was not running or properly listening on a port when `supertest` attempted to make a request, or the server instance was terminated prematurely.
  fix Verify that your server application is correctly started before tests run (`beforeAll`) and shut down afterward (`afterAll`). If using `supertest` with an Express app, ensure you pass the app instance directly to `request(app)` rather than a URL.

• HTTP Error: 500 Internal Server Error

  cause A runtime error occurred within your GraphQL resolvers or server middleware that was not caught and formatted by the GraphQL server, resulting in a generic HTTP 500 status.
  fix Inspect the server logs for the full stack trace of the internal server error. Add error handling and logging to your GraphQL resolvers and middleware to surface more specific error messages in the test response.

• GraphQL error: Cannot query field 'X' on type 'Y'.

  cause The GraphQL query sent in the test is requesting a field that does not exist on the specified type in your GraphQL schema.
  fix Compare the problematic query in your test with your GraphQL schema definition. Correct the query to match the available fields and types in your schema, paying attention to casing and nesting.

Warnings

• breaking Major version updates (e.g., from v1 to v2) of `supertest` or underlying HTTP server frameworks (like Express or Apollo Server) can introduce breaking changes that might require updates to how the server application is configured or passed to `createTestClient`. Always review the changelogs of all dependent packages.
  Fix: Consult the changelogs of `supertest`, your GraphQL server library (e.g., Apollo Server), and `graphql-server-test` for specific migration steps. Typically involves updating how the server is instantiated or middleware is applied.
• gotcha Improper server lifecycle management in tests (e.g., not starting/stopping the HTTP server for each test suite or test file) can lead to 'address already in use' errors or resource leaks, especially with frameworks like Express or Apollo Server.
  Fix: Ensure `beforeAll`/`afterAll` or `beforeEach`/`afterEach` hooks are used correctly to manage the HTTP server's lifecycle. For `supertest`, pass the `express` app directly to `request()` without explicitly calling `listen()` in tests, as `supertest` handles this internally.
• gotcha GraphQL context in tests may not accurately reflect production if not explicitly set up. Authentication, authorization, and data source injection often depend on the context object, which needs to be properly mocked or constructed for tests.
  Fix: When initializing your GraphQL server for testing, ensure that context functions or objects are configured to provide the necessary test-specific values, such as mocked users, data sources, or authentication tokens.
• gotcha Asynchronous operations (queries, mutations) in GraphQL tests must be handled correctly with `async/await` to prevent flaky tests or incorrect assertions, as responses are Promises.
  Fix: Always use `await` when calling `client.query()` or `client.mutate()` and within `async` test functions. Ensure your test runner is configured to handle asynchronous tests (e.g., Jest's `done()` callback or returning a Promise).

Install

• npm install graphql-server-test npm
• yarn add graphql-server-test yarn
• pnpm add graphql-server-test pnpm

Imports

• createTestClient
  wrong:

  const createTestClient = require('graphql-server-test');

  correct:

  import { createTestClient } from 'graphql-server-test';

  The library primarily uses named exports and is designed for ESM contexts. While CJS might work via transpilation, direct `require` is discouraged for modern Node.js environments.
• GraphQLTestClient
  wrong:

  import { GraphQLTestClient } from 'graphql-server-test';

  correct:

  import type { GraphQLTestClient } from 'graphql-server-test';

  This is a TypeScript type definition for the client object returned by `createTestClient`. It should be imported using `import type` to avoid runtime bundle inclusion.
• gql

  import { gql } from 'graphql-server-test';

  A utility tag function to parse GraphQL query strings, similar to `graphql-tag` or `apollo-server`'s `gql`.

Quickstart

This quickstart demonstrates how to set up an Apollo Server with Express and use `graphql-server-test` to perform integration tests for queries and mutations, including context passing.

import request from 'supertest';
import { ApolloServer } from '@apollo/server';
import { expressMiddleware } from '@apollo/server/express4';
import { ApolloServerPluginDrainHttpServer } from '@apollo/server/plugin/drainHttpServer';
import express from 'express';
import http from 'http';
import { createTestClient, gql } from 'graphql-server-test';

interface MyContext { user?: { id: string, name: string }; }

const typeDefs = `#graphql
  type User {
    id: ID!
    name: String!
  }

  type Query {
    hello: String!
    me: User
  }

  type Mutation {
    createUser(name: String!): User!
  }
`;

const users: { id: string, name: string }[] = [];
let nextId = 1;

const resolvers = {
  Query: {
    hello: () => 'world',
    me: (_: any, __: any, context: MyContext) => context.user,
  },
  Mutation: {
    createUser: (_: any, { name }: { name: string }) => {
      const newUser = { id: String(nextId++), name };
      users.push(newUser);
      return newUser;
    },
  },
};

async function startApolloServer() {
  const app = express();
  const httpServer = http.createServer(app);
  const server = new ApolloServer<MyContext>({
    typeDefs,
    resolvers,
    plugins: [ApolloServerPluginDrainHttpServer({ httpServer })],
  });

  await server.start();

  app.use('/graphql', express.json(), expressMiddleware(server, {
    context: async ({ req }) => {
      const token = req.headers.authorization || '';
      // Mock user for testing purposes
      if (token === 'Bearer testuser') {
        return { user: { id: '123', name: 'Test User' } };
      }
      return {};
    },
  }));

  return app;
}

describe('GraphQL Server Integration Tests', () => {
  let app: express.Application;
  let client: ReturnType<typeof createTestClient>;

  beforeAll(async () => {
    app = await startApolloServer();
    client = createTestClient(request(app));
  });

  it('should return "world" for the hello query', async () => {
    const response = await client.query(gql`query { hello }`);
    expect(response.status).toBe(200);
    expect(response.body.data.hello).toBe('world');
  });

  it('should return the authenticated user', async () => {
    const response = await client.query(
      gql`query { me { id name } }`,
      { headers: { Authorization: 'Bearer testuser' } }
    );
    expect(response.status).toBe(200);
    expect(response.body.data.me).toEqual({ id: '123', name: 'Test User' });
  });

  it('should create a new user via mutation', async () => {
    const response = await client.mutate(
      gql`mutation CreateUser($name: String!) { createUser(name: $name) { id name } }`,
      { variables: { name: 'New User' } }
    );
    expect(response.status).toBe(200);
    expect(response.body.data.createUser).toHaveProperty('id');
    expect(response.body.data.createUser.name).toBe('New User');
  });
});