Registry / testing / graphql-server-test

graphql-server-test

JSON →
library2.12.6jsnpmunverified

The `graphql-server-test` library provides utilities for performing constructive HTTP-level integration and end-to-end testing of GraphQL servers. Leveraging the popular `supertest` library, it enables developers to simulate actual HTTP requests against their GraphQL endpoint, ensuring that the entire server stack—including middleware, authentication, and database interactions—behaves as expected. Currently at version 2.12.6, this package is actively maintained and ships with TypeScript type definitions, facilitating type-safe test development. Its primary differentiator is its focus on black-box HTTP testing for GraphQL, making it suitable for any server implementation (e.g., Apollo Server, Express-GraphQL) by interacting with it as a standard HTTP service. This approach contrasts with unit testing individual resolvers, offering a more realistic assessment of the GraphQL API's functionality in production-like environments.

npm install graphql-server-test
INSTALL
IMPORT
SIG · GRAPHQL-SERVER-TES
G
graphql-server-test
testingjavascriptv2.12.6
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

createTestClient
import { createTestClient } from 'graphql-server-test';
const createTestClient = require('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
import type { GraphQLTestClient } from 'graphql-server-test';
import { 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`.

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'); }); });
Debug
Known issues
breakingMajor 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.
affects: >=2.0.0
gotchaImproper 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.
affects: >=1.0.0
gotchaGraphQL 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.
affects: >=1.0.0
gotchaAsynchronous 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).
affects: >=1.0.0
Errors
Common errors & fixes
TypeError: Schema must be an instance of GraphQLSchema.
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)
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
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'.
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.
Upgrade
Version history
2.12.6latest on npm
Audit
Dependencies
supertestrequiredCore dependency for making HTTP assertions against the GraphQL server.
graphqlrequiredNeeded for parsing and executing GraphQL queries and understanding schema definitions within tests.
Agent activity
7 hits · last 30 days
node
6
Resources
graphql-server-test — npm install graphql-server-test · libregistry