Integration Testing
Utilities for testing Apollo Server
Apollo Server uses a multi-step request pipeline to validate and execute incoming GraphQL operations. This pipeline supports integration with custom plugins at each step, which can affect an operation's execution. Because of this, it's important to perform integration tests with a variety of operations to ensure your request pipeline works as expected.
There are two main options for integration testing with Apollo Server:
-
Using
ApolloServer'sexecuteOperationmethod. Setting up an HTTP client to query your server.
Testing using executeOperation
Apollo Server's executeOperation method enables you to run operations through the request pipeline without sending an HTTP request.
The executeOperation method accepts the following arguments:
An object that describes the GraphQL operation to execute.
This object must include a
queryfield specifying the GraphQL operation to run. You can useexecuteOperationto execute both queries and mutations, but both use thequeryfield.
An optional second object that is used as the operation's
contextValue).
Below is a simplified example of setting up a test using the JavaScript testing library Jest:
1// For clarity in this example we included our typeDefs and resolvers above our test,
2// but in a real world situation you'd be importing these in from different files
3const typeDefs = `#graphql
4 type Query {
5 hello(name: String): String!
6 }
7`;
8
9const resolvers = {
10 Query: {
11 hello: (_, { name }) => `Hello ${name}!`,
12 },
13};
14
15it('returns hello with the provided name', async () => {
16 const testServer = new ApolloServer({
17 typeDefs,
18 resolvers,
19 });
20
21 const response = await testServer.executeOperation({
22 query: 'query SayHelloWorld($name: String) { hello(name: $name) }',
23 variables: { name: 'world' },
24 });
25
26 // Note the use of Node's assert rather than Jest's expect; if using
27 // TypeScript, `assert`` will appropriately narrow the type of `body`
28 // and `expect` will not.
29 assert(response.body.kind === 'single');
30 expect(response.body.singleResult.errors).toBeUndefined();
31 expect(response.body.singleResult.data?.hello).toBe('Hello world!');
32});Note that when testing, any errors in parsing, validating, and executing your GraphQL operation are returned in the nested errors field of the result. As with any GraphQL response, these errors are not thrown.
You don't need to start your server before calling executeOperation. The server instance will start automatically and throw any startup errors.
To expand on the example above, here's a full integration test being run against a test instance of ApolloServer. This test imports all of the important pieces to test (typeDefs, resolvers, dataSources) and creates a new instance of ApolloServer.
1it('fetches single launch', async () => {
2 const userAPI = new UserAPI({ store });
3 const launchAPI = new LaunchAPI();
4
5 // ensure our server's context is typed correctly
6 interface ContextValue {
7 user: User;
8 dataSources: {
9 userAPI: UserAPI;
10 launchAPI: LaunchAPI;
11 };
12 }
13
14 // create a test server to test against, using our production typeDefs,
15 // resolvers, and dataSources.
16 const server = new ApolloServer<ContextValue>({
17 typeDefs,
18 resolvers,
19 });
20
21 // mock the dataSource's underlying fetch methods
22 launchAPI.get = jest.fn(() => [mockLaunchResponse]);
23 userAPI.store = mockStore;
24 userAPI.store.trips.findAll.mockReturnValueOnce([
25 { dataValues: { launchId: 1 } },
26 ]);
27
28 // run the query against the server and snapshot the output
29 const res = await server.executeOperation(
30 {
31 query: GET_LAUNCH,
32 variables: { id: 1 },
33 },
34 {
35 contextValue: {
36 user: { id: 1, email: '[email protected]' },
37 dataSources: {
38 userAPI,
39 launchAPI,
40 },
41 },
42 },
43 );
44
45 expect(res).toMatchSnapshot();
46});The example above includes a test-specific context value, which provides data directly to the ApolloServer instance, bypassing any context initialization function you have.
If you want to test the behavior of your context function directly, we recommend running actual HTTP requests against your server.
For examples of both integration and end-to-end testing we recommend checking out the tests included in the Apollo fullstack tutorial.
End-to-end testing
Instead of bypassing the HTTP layer, you might want to fully run your server and test it with a real HTTP client. Apollo Server doesn't provide built-in support for this at this time.
Instead, you can run operations against your server using a combination of any HTTP or GraphQL client such as supertest or Apollo Client's HTTP Link.
Below is an example of writing an end-to-end test using the @apollo/server and supertest packages:
1// we import a function that we wrote to create a new instance of Apollo Server
2import { createApolloServer } from '../server';
3
4// we'll use supertest to test our server
5import request from 'supertest';
6
7// this is the query for our test
8const queryData = {
9 query: `query sayHello($name: String) {
10 hello(name: $name)
11 }`,
12 variables: { name: 'world' },
13};
14
15describe('e2e demo', () => {
16 let server, url;
17
18 // before the tests we spin up a new Apollo Server
19 beforeAll(async () => {
20 // Note we must wrap our object destructuring in parentheses because we already declared these variables
21 // We pass in the port as 0 to let the server pick its own ephemeral port for testing
22 ({ server, url } = await createApolloServer({ port: 0 }));
23 });
24
25 // after the tests we'll stop the server
26 afterAll(async () => {
27 await server?.stop();
28 });
29
30 it('says hello', async () => {
31 // send our request to the url of the test server
32 const response = await request(url).post('/').send(queryData);
33 expect(response.errors).toBeUndefined();
34 expect(response.body.data?.hello).toBe('Hello world!');
35 });
36});You can also view and fork this complete example on CodeSandbox:
Edit in CodeSandbox