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
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
createTestClient
✓ import { createTestClient } from 'apollo-server-testing';
✗ import { createTestClient } from '@apollo/server/testing';
This specific import is for `apollo-server-testing` (v2/v3). For `@apollo/server` (v4+), testing is typically done directly with `server.executeOperation` or `@apollo/server/testing` if available for specific integrations. The `apollo-server-testing` package is deprecated and will not be published with Apollo Server 3 onwards.
ApolloServer
✓ import { ApolloServer, gql } from 'apollo-server';
✗ import { ApolloServer } from '@apollo/server';
This package integrates with `apollo-server` (v2/v3). The modern equivalent for v4+ is `@apollo/server` which has a different import path and API. Make sure you are using the correct `ApolloServer` instance that matches your project's main Apollo Server version.
This quickstart demonstrates how to use `apollo-server-testing` with `apollo-server` (v2/v3) to create an in-memory test client and execute GraphQL queries and mutations against a defined schema and resolvers, simulating requests without a live HTTP server. This is suitable for integration tests of the GraphQL layer.
import { ApolloServer, gql } from 'apollo-server';
import { createTestClient } from 'apollo-server-testing';
// 1. Define your GraphQL schema
const typeDefs = gql`
type Query {
hello(name: String): String!
getUser(id: ID!): User
}
type User {
id: ID!
name: String!
email: String!
}
type Mutation {
addUser(name: String!, email: String!): User!
}
`;
// 2. Define your resolvers
const users = [
{ id: '1', name: 'Alice', email: 'alice@example.com' },
{ id: '2', name: 'Bob', email: 'bob@example.com' }
];
const resolvers = {
Query: {
hello: (_, { name }) => `Hello ${name || 'World'}!`,
getUser: (_, { id }) => users.find(user => user.id === id)
},
Mutation: {
addUser: (_, { name, email }) => {
const newUser = { id: String(users.length + 1), name, email };
users.push(newUser);
return newUser;
}
}
};
// 3. Create an Apollo Server instance
const server = new ApolloServer({
typeDefs,
resolvers,
// Optional: context function
context: () => ({ /* Add any context relevant for your resolvers */ })
});
// 4. Create a test client
const { query, mutate } = createTestClient(server);
// Example Test (using Jest syntax for illustration)
describe('Apollo Server Integration Tests', () => {
it('should fetch a greeting', async () => {
const GET_HELLO = gql`
query GetHello($name: String) {
hello(name: $name)
}
`;
const response = await query({ query: GET_HELLO, variables: { name: 'Test' } });
expect(response.data.hello).toBe('Hello Test!');
});
it('should add a new user', async () => {
const ADD_USER = gql`
mutation AddUser($name: String!, $email: String!) {
addUser(name: $name, email: $email) {
id
name
email
}
}
`;
const response = await mutate({ query: ADD_USER, variables: { name: 'Charlie', email: 'charlie@example.com' } });
expect(response.data.addUser).toEqual({
id: expect.any(String),
name: 'Charlie',
email: 'charlie@example.com'
});
expect(users).toHaveLength(3);
});
it('should fetch an existing user', async () => {
const GET_USER = gql`
query GetUser($id: ID!) {
getUser(id: $id) {
id
name
email
}
}
`;
const response = await query({ query: GET_USER, variables: { id: '1' } });
expect(response.data.getUser).toEqual(users[0]);
});
});
Debug
Known issues
breakingThe `apollo-server-testing` package is designed for Apollo Server v2 and v3. Both v2 (end-of-life Oct 2023) and v3 (end-of-life Oct 2024) are no longer officially supported by Apollo. New projects should use `@apollo/server` (v4+) and its integrated testing approaches.fixFor new projects or migrations, switch to `@apollo/server` (v4+) and utilize `server.executeOperation` directly for testing, or use specific integration testing packages like `apollo-server-integration-testing` if full HTTP layer simulation is needed.
affects: >=3.0.0 (of `apollo-server`)
gotchaThe `createTestClient` function from `apollo-server-testing` does not fully support the `context` function argument that Apollo Server's `executeOperation` method (and the server itself) provides. Specifically, it might not pass `req` or `res` objects to your context function as expected, leading to `undefined` values if your context relies on them.fixIf your context function depends on `req` or `res`, you'll need to mock these objects within your test context or adjust your context logic for testing. Alternatively, consider using `server.executeOperation` directly and explicitly passing a test-specific context object, or using an integration testing package that properly mocks HTTP requests and responses.
affects: >=2.0.0
deprecatedThe `apollo-server-testing` package is explicitly deprecated and will not be published with Apollo Server 3 or later. Its functionality is a thin wrapper around `ApolloServer.executeOperation`, which is the recommended direct approach for testing Apollo Server logic without the HTTP layer.fixMigrate your tests to directly use the `ApolloServer` instance's `executeOperation` method. This method provides the same core functionality and is the officially supported way to test GraphQL operations in isolation for Apollo Server v2+. For Apollo Server v4+, the new core `@apollo/server` package has `executeOperation` built-in.
affects: >=2.0.0
Errors
Common errors & fixes
TypeError: Cannot destructure property 'query' of 'undefined' as it is undefined.
This typically occurs if `createTestClient` is called with an `ApolloServer` instance that hasn't been properly initialized or started, or if `apollo-server-testing` is being used with `@apollo/server` (v4+), which doesn't directly expose `createTestClient`.
fixEnsure your `ApolloServer` instance (from `apollo-server` v2/v3) is correctly constructed before passing it to `createTestClient`. If using `@apollo/server` v4+, you should directly use `server.executeOperation()` instead of `createTestClient()`.
Error: Apollo Server requires 'graphql' to be installed. Please install 'graphql@^14.0.0 || ^15.0.0' or newer.
Missing `graphql` peer dependency or an incompatible version is installed. `apollo-server-testing` depends on `apollo-server` which has `graphql` as a peer dependency.
fixInstall the required `graphql` version: `npm install graphql@^14.0.0 || ^15.0.0` or `yarn add graphql@^14.0.0 || ^15.0.0`. Refer to your `apollo-server` version's documentation for exact compatible `graphql` versions.
Audit
Dependencies
graphqlrequiredRequired for GraphQL schema definition and execution, a peer dependency for Apollo Server.
apollo-serverrequiredThis package is a testing utility for the Apollo Server core, specifically versions 2.x and 3.x.