Deprecate apollo-server-testing; allow ASTs for executeOperation (#5238)

The `apollo-server-testing` package exports one small function which is
just a tiny wrapper around `server.executeOperation`. The one main
advantage it provides is that you can pass in operations as ASTs rather
than only as strings.

This extra layer doesn't add much value but does require us to update
things in two places (which cross a package barrier and thus can be
installed at skewed versions). So for example when adding the second
argument to `executeOperation` in #4166 I did not bother to add it to
`apollo-server-testing` too. We've also found that users have been
confused by the `createTestClient` API (eg #5111) and that some linters
get confused by the unbound methods it returns (#4724).

So the simplest thing is to just teach people how to use the real
`ApolloServer` method instead of an unrelated API.

This PR allows you to pass an AST to `server.executeOperation` (just
like with the `apollo-server-testing` API), and changes the docs to
recommend `executeOperation` instead of `apollo-server-testing`. It also
makes some other suggestions about how to test Apollo Server code in a
more end-to-end fashion, and adds some basic tests for
`executeOperation`.

Fixes #4952.

Author: glasser

CHANGELOG.md

@@ -13,6 +13,8 @@ The version headers in this history reflect the versions of Apollo Server itself
 
 - `apollo-server-core`: Fix a race condition where schema reporting could lead to a delay at process shutdown. [PR #5222](https://github.com/apollographql/apollo-server/pull/5222)
 - `apollo-server-core`: Allow the Fetch API implementation to be overridden for the schema reporting and usage reporting plugins via a new `fetcher` option. [PR #5179](https://github.com/apollographql/apollo-server/pull/5179)
+- `apollo-server-core`: The `server.executeOperation` method (designed for testing) can now take its `query` as a `DocumentNode` (eg, a `gql`-tagged string) in addition to as a string. (This matches the behavior of the `apollo-server-testing` `createTestClient` function which is now deprecated.) We now recommend this method instead of `apollo-server-testing` in our docs. [Issue #4952](https://github.com/apollographql/apollo-server/issues/4952)
+- `apollo-server-testing`: Replace README with a deprecation notice explaining how to use `server.executeOperation` instead. [Issue #4952](https://github.com/apollographql/apollo-server/issues/4952)
 
 ## v2.24.1
 

docs/source/testing/testing.md

@@ -3,33 +3,26 @@ title: Integration testing
 description: Utilities for testing Apollo Server
 ---
 
-Testing `apollo-server` can be done in many ways. The `apollo-server-testing` package provides tooling to make testing easier and accessible to users of all of the `apollo-server` integrations.
+Testing `apollo-server` can be done in many ways. One simple way is to use ApolloServer's `executeOperation` method to directly execute a GraphQL operation without going through a full HTTP operation.
 
-## `createTestClient`
+## `executeOperation`
 
-Integration testing a GraphQL server means testing many things. `apollo-server` has a request pipeline that can support many plugins that can affect the way an operation is executed. `createTestClient` provides a single hook to run operations through the request pipeline, enabling the most thorough tests possible without starting up an HTTP server.
+Integration testing a GraphQL server means testing many things. `apollo-server` has a request pipeline that can support many plugins that can affect the way an operation is executed. The `executeOperation` method provides a single hook to run operations through the request pipeline, enabling the most thorough tests possible without starting up an HTTP server.
 
 ```javascript
-const { createTestClient } = require('apollo-server-testing');
-
-const { query, mutate } = createTestClient(server);
+const server = new ApolloServer(config);
 
-query({
+const result = await server.executeOperation({
   query: GET_USER,
   variables: { id: 1 }
 });
-
-mutate({
-  mutation: UPDATE_USER,
-  variables: { id: 1, email: 'nancy@foo.co' }
-});
+expect(result.errors).toBeUndefined();
+expect(result.data?.user.name).toBe('Ida');
 ```
 
-When passed an instance of the `ApolloServer` class, `createTestClient` returns a `query` and `mutate` function that can be used to run operations against the server instance. Currently, queries and mutations are the only operation types supported by `createTestClient`.
+For example, you can set up a full server with your schema and resolvers and run an operation against it.
 
 ```javascript
-const { createTestClient } = require('apollo-server-testing');
-
 it('fetches single launch', async () => {
   const userAPI = new UserAPI({ store });
   const launchAPI = new LaunchAPI();
@@ -42,6 +35,7 @@ it('fetches single launch', async () => {
     dataSources: () => ({ userAPI, launchAPI }),
     context: () => ({ user: { id: 1, email: 'a@a.a' } }),
   });
+  await server.start();
 
   // mock the dataSource's underlying fetch methods
   launchAPI.get = jest.fn(() => [mockLaunchResponse]);
@@ -50,15 +44,46 @@ it('fetches single launch', async () => {
     { dataValues: { launchId: 1 } },
   ]);
 
-  // use the test server to create a query function
-  const { query } = createTestClient(server);
-
   // run query against the server and snapshot the output
-  const res = await query({ query: GET_LAUNCH, variables: { id: 1 } });
+  const res = await server.executeOperation({ query: GET_LAUNCH, variables: { id: 1 } });
   expect(res).toMatchSnapshot();
 });
 ```
 
-This is an example of a full integration test being run against a test instance of `apollo-server`. This test imports the important pieces to test (`typeDefs`, `resolvers`, `dataSources`) and creates a new instance of `apollo-server`. Once an instance is created, it's passed to `createTestClient` which returns `{ query, mutate }`. These methods can then be used to execute operations against the server.
+This is an example of a full integration test being run against a test instance of `apollo-server`. This test imports the important pieces to test (`typeDefs`, `resolvers`, `dataSources`) and creates a new instance of `apollo-server`.
+
+The example above shows writing a test-specific [`context` function](../data/resolvers/#the-context-argument) which provides data directly instead of calculating it from the request context. If you'd like to use your server's real `context` function, you can pass a second argument to `executeOperation` which will be passed to your `context` function as its argument. You will need to put to gether an object with the [middleware-specific context fields](../api/apollo-server/#middleware-specific-context-fields) yourself.
+
+You can use `executeOperation` to execute queries and mutations. Because the interface matches the GraphQL HTTP protocol, you specify the operation text under the `query` key even if the operation is a mutation. You can specify `query` either as a string or as a `DocumentNode` (an AST created by the `gql` tag).
+
+In addition to `query`, the first argument to `executeOperation` can take `operationName`, `variables`, `extensions`, and `http` keys.
+
+Note that errors in parsing, validating, and executing your operation are returned in the `errors` field of the result (just like in a GraphQL response) rather than thrown.
+
+## `createTestClient` and `apollo-server-testing`
+
+There is also a package called `apollo-server-testing` which exports a function `createTestClient` which wraps `executeOperation`. This API does not support the second context-function-argument argument, and doesn't provide any real advantages over calling `executeOperation` directly. It is deprecated and will no longer be published with Apollo Server 3.
+
+We recommend that you replace this code:
+
+```js
+const { createTestClient } = require('apollo-server-testing');
+
+const { query, mutate } = createTestClient(server);
+
+await query({ query: QUERY });
+await mutate({ mutation: MUTATION });
+```
+
+with
+
+```js
+await server.executeOperation({ query: QUERY });
+await server.executeOperation({ query: MUTATION });
+```
+
+## End-to-end testing
+
+Instead of bypassing the HTTP layer, you may just want to fully run your server and test it with a real HTTP client.
 
-For more examples of this tool in action, check out the [integration tests](https://github.com/apollographql/fullstack-tutorial/blob/master/final/server/src/__tests__/integration.js) in the [Fullstack Tutorial](https://www.apollographql.com/docs/tutorial/introduction.html).
+Apollo Server doesn't have any built-in support for this. You can combine any HTTP or GraphQL client such as [`supertest`](https://www.npmjs.com/package/supertest) or [Apollo Client's HTTP Link](https://www.apollographql.com/docs/react/api/link/apollo-link-http/) to run operations against your server. There are also community packages available such as [`apollo-server-integration-testing`](https://www.npmjs.com/package/apollo-server-integration-testing) which provides an API similar to the deprecated `apollo-server-testing` package which uses mocked Express request and response objects.

packages/apollo-server-core/src/ApolloServer.ts

@@ -19,6 +19,7 @@ import {
   ValidationContext,
   FieldDefinitionNode,
   DocumentNode,
+  print,
 } from 'graphql';
 import resolvable, { Resolvable } from '@josephg/resolvable';
 import { GraphQLExtension } from 'graphql-extensions';
@@ -1265,6 +1266,11 @@ export class ApolloServerBase {
    * going through the HTTP layer. Note that this means that any handling you do
    * in your server at the HTTP level will not affect this call!
    *
+   * For convenience, you can provide `request.query` either as a string or a
+   * DocumentNode, in case you choose to use the gql tag in your tests. This is
+   * just a convenience, not an optimization (we convert provided ASTs back into
+   * string).
+   *
    * If you pass a second argument to this method and your ApolloServer's
    * `context` is a function, that argument will be passed directly to your
    * `context` function. It is your responsibility to make it as close as needed
@@ -1273,7 +1279,12 @@ export class ApolloServerBase {
    * `{req: express.Request, res: express.Response }` object) and to keep it
    * updated as you upgrade Apollo Server.
    */
-  public async executeOperation(request: GraphQLRequest, integrationContextArgument?: Record<string, any>) {
+  public async executeOperation(
+    request: Omit<GraphQLRequest, 'query'> & {
+      query?: string | DocumentNode;
+    },
+    integrationContextArgument?: Record<string, any>,
+  ) {
     const options = await this.graphQLServerOptions(integrationContextArgument);
 
     if (typeof options.context === 'function') {
@@ -1292,7 +1303,13 @@ export class ApolloServerBase {
       logger: this.logger,
       schema: options.schema,
       schemaHash: options.schemaHash,
-      request,
+      request: {
+        ...request,
+        query:
+          request.query && typeof request.query !== 'string'
+            ? print(request.query)
+            : request.query,
+      },
       context: options.context || Object.create(null),
       cache: options.cache!,
       metrics: {},

packages/apollo-server-core/src/__tests__/ApolloServerBase.test.ts

@@ -1,6 +1,6 @@
 import { ApolloServerBase } from '../ApolloServer';
 import { buildServiceDefinition } from '@apollographql/apollo-tools';
-import gql from 'graphql-tag';
+import { gql } from '../';
 import { Logger } from 'apollo-server-types';
 import { ApolloServerPlugin } from 'apollo-server-plugin-base';
 import type { GraphQLSchema } from 'graphql';
@@ -9,6 +9,7 @@ const typeDefs = gql`
   type Query {
     hello: String
     error: Boolean
+    contextFoo: String
   }
 `;
 
@@ -20,6 +21,9 @@ const resolvers = {
     error() {
       throw new Error('A test error');
     },
+    contextFoo(_root: any, _args: any, context: any) {
+      return context.foo;
+    },
   },
 };
 
@@ -181,6 +185,60 @@ describe('ApolloServerBase executeOperation', () => {
     expect(result.errors?.[0].extensions?.code).toBe('INTERNAL_SERVER_ERROR');
     expect(result.errors?.[0].extensions?.exception?.stacktrace).toBeDefined();
   });
+
+  it('works with string', async () => {
+    const server = new ApolloServerBase({
+      typeDefs,
+      resolvers,
+    });
+
+    const result = await server.executeOperation({ query: '{ hello }' });
+    expect(result.errors).toBeUndefined();
+    expect(result.data?.hello).toBe('world');
+  });
+
+  it('works with AST', async () => {
+    const server = new ApolloServerBase({
+      typeDefs,
+      resolvers,
+    });
+
+    const result = await server.executeOperation({
+      query: gql`
+        {
+          hello
+        }
+      `,
+    });
+    expect(result.errors).toBeUndefined();
+    expect(result.data?.hello).toBe('world');
+  });
+
+  it('parse errors', async () => {
+    const server = new ApolloServerBase({
+      typeDefs,
+      resolvers,
+    });
+
+    const result = await server.executeOperation({ query: '{' });
+    expect(result.errors).toHaveLength(1);
+    expect(result.errors?.[0].extensions?.code).toBe('GRAPHQL_PARSE_FAILED');
+  });
+
+  it('passes its second argument to context function', async () => {
+    const server = new ApolloServerBase({
+      typeDefs,
+      resolvers,
+      context: ({ fooIn }) => ({ foo: fooIn }),
+    });
+
+    const result = await server.executeOperation(
+      { query: '{ contextFoo }' },
+      { fooIn: 'bla' },
+    );
+    expect(result.errors).toBeUndefined();
+    expect(result.data?.contextFoo).toBe('bla');
+  });
 });
 
 describe('environment variables', () => {

packages/apollo-server-testing/README.md

@@ -1,7 +1,23 @@
 # apollo-server-testing
 
-[![npm version](https://badge.fury.io/js/apollo-server-testing.svg)](https://badge.fury.io/js/apollo-server-testing)
-[![Build Status](https://circleci.com/gh/apollographql/apollo-server/tree/main.svg?style=svg)](https://circleci.com/gh/apollographql/apollo-server)
+This deprecated package contains a function `createTestClient` which is a very thin wrapper around the Apollo Server `server.executeOperation` method.
 
-This is the testing module of the Apollo community GraphQL Server. [Read the docs.](https://www.apollographql.com/docs/apollo-server/)
-[Read the CHANGELOG.](https://github.com/apollographql/apollo-server/blob/main/CHANGELOG.md)
+Code that uses this package looks like the following, where `server` is an `ApolloServer`:
+
+```js
+const { createTestClient } = require('apollo-server-testing');
+
+const { query, mutate } = createTestClient(server);
+
+await query({ query: QUERY });
+await mutate({ mutation: MUTATION });
+```
+
+We recommend you stop using this package and replace the above code with the equivalent:
+
+```js
+await server.executeOperation({ query: QUERY });
+await server.executeOperation({ query: MUTATION });
+```
+
+This package will not be distributed as part of Apollo Server 3.