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-testVerified import paths — ran on the pinned version, not inferred.
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.
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.
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.
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.
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).
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`.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.
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.
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.