Registry /
testing / apollo-server-integration-testing
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-integration-testing';
✗ const { createTestClient } = require('apollo-server-integration-testing');
The library primarily exports `createTestClient` as a named export. While CommonJS `require` syntax might technically work in some environments, modern TypeScript/JavaScript projects should use ESM `import`.
TestClient
✓ import type { TestClient } from 'apollo-server-integration-testing';
When using TypeScript, import the `TestClient` type for type-safety when destructuring `query` and `mutate`.
setOptions
✓ const { query, setOptions } = createTestClient({ apolloServer });
The `setOptions` function is returned alongside `query` and `mutate` and allows modifying mock request/response options dynamically after client creation, which can be more efficient than re-creating the client for each change.
This quickstart demonstrates how to create an Apollo Server, use `createTestClient` to run queries and mutations against it, mock and extend the `Request` object for context testing, and dynamically update mock options using `setOptions`. It includes mandatory `server.start()` and `server.stop()` calls for Apollo Server v3+.
import { createTestClient } from 'apollo-server-integration-testing';
import { ApolloServer } from '@apollo/server';
import { buildSubgraphSchema } from '@apollo/subgraph';
import gql from 'graphql-tag';
const typeDefs = gql`
type User {
id: ID!
email: String
}
type Query {
currentUser: User
}
type Mutation {
updateUser(id: ID!, email: String!): User
}
`;
const resolvers = {
Query: {
currentUser: (_, __, { req }) => {
// Simulate context logic that depends on req
if (req?.headers?.authorization) {
return { id: '1', email: 'test@example.com' };
}
return null;
},
},
Mutation: {
updateUser: (_, { id, email }) => ({ id, email }),
},
};
async function createApolloServer() {
const server = new ApolloServer({
schema: buildSubgraphSchema({ typeDefs, resolvers }),
});
await server.start(); // Mandatory for Apollo Server v3+
return server;
}
describe('Apollo Server Integration Tests', () => {
let apolloServer;
let query;
let mutate;
let setOptions;
beforeAll(async () => {
apolloServer = await createApolloServer();
({ query, mutate, setOptions } = createTestClient({
apolloServer,
extendMockRequest: {
headers: { authorization: 'Bearer token' }
}
}));
});
afterAll(async () => {
await apolloServer.stop();
});
test('should fetch current user with mocked request headers', async () => {
const result = await query(`{ currentUser { id email } }`);
expect(result).toEqual({
data: {
currentUser: {
id: '1',
email: 'test@example.com'
}
}
});
});
test('should update user and allow subsequent request modification', async () => {
setOptions({
request: { headers: { authorization: 'Bearer another-token' } }
});
const UPDATE_USER_MUTATION = `
mutation UpdateUser($id: ID!, $email: String!) {
updateUser(id: $id, email: $email) {
id
email
}
}
`;
const mutationResult = await mutate(UPDATE_USER_MUTATION, {
variables: { id: '1', email: 'jane.doe@example.com' }
});
expect(mutationResult).toEqual({
data: {
updateUser: {
id: '1',
email: 'jane.doe@example.com'
}
}
});
});
});
Debug
Known issues
gotchaWhen testing Apollo Server `context` functions that rely on `req` or `res` objects, using the official `apollo-server-testing` package (now deprecated in favor of `server.executeOperation`) will result in `req` being `undefined`. This package (`apollo-server-integration-testing`) is specifically designed to address this limitation by providing robust mock HTTP request/response objects.fixUse `apollo-server-integration-testing` for integration tests where your `ApolloServer` instance's `context` option is a function that processes the incoming `req` or `res` objects. For simpler, isolated GraphQL operation tests, consider `ApolloServer.executeOperation` directly.
affects: >=1.0.0
breakingApollo Server v3 and later versions require calling `await server.start()` before the server can be used. Failing to do so will result in runtime errors. This applies when you are passing an `ApolloServer` instance to `createTestClient`.fixEnsure you call `await apolloServer.start()` after creating your `ApolloServer` instance and before passing it to `createTestClient`.
affects: >=3.0.0 of Apollo Server
gotchaThe `graphql` peer dependency for `apollo-server-integration-testing` has a wide range (`^0.12.0 || ^0.13.0 || ^14.0.0 || ^15.0.0`). However, the specific version of `graphql` required by your `Apollo Server` package (e.g., Apollo Server 3 requires `graphql` v15.3.0+, Apollo Server 4 requires `graphql` v16+) might be more restrictive. A mismatch can lead to unexpected behavior or conflicts.fixAlways install a `graphql` version that satisfies both `apollo-server-integration-testing`'s peer dependency and, more importantly, the explicit requirements of your specific `Apollo Server` package.
affects: All versions, depending on `Apollo Server` version
Errors
Common errors & fixes
Cannot read properties of undefined (reading 'req') / TypeError: Cannot read property 'req' of undefined
Attempting to access `req` (or `res`) within the `ApolloServer`'s `context` function when using `apollo-server-testing` or `ApolloServer.executeOperation` for a test where `req` is not explicitly mocked.
fixSwitch to `apollo-server-integration-testing` for tests that require `req` or `res` objects in the `context`, or manually mock the `context` argument when using `ApolloServer.executeOperation` if a full HTTP mock isn't needed. Alternatively, if using `apollo-server-integration-testing`, ensure `extendMockRequest` or `setOptions` provide the necessary `req` properties.
ApolloServer must be started before it can be used. Call `await server.start()` before `applyMiddleware()` or `listen()`.
When using Apollo Server v3 or later, the `server.start()` method must be called to initialize the server before any operations or integrations can use it. This error indicates it was omitted before `createTestClient` was invoked.
fixAdd `await apolloServer.start();` after creating your `new ApolloServer(...)` instance and before passing `apolloServer` to `createTestClient`.
Audit
Dependencies
graphqlrequiredRequired as a peer dependency for GraphQL schema validation and execution. Note that the supported range (`^0.12.0 || ^0.13.0 || ^14.0.0 || ^15.0.0`) is broad and should be compatible with the specific Apollo Server version being tested.