Skip to main content

GraphQL API

GraphQL is simply an abstraction over HTTP and may be tested via Pact.

Support​

RoleInterfaceSupported?
ConsumerPact✅
ConsumerPactV3✅
ConsumerPactV2✅
ProviderVerifier✅

API​

The Pact class provides addGraphQLInteraction() which returns a fluent builder specifically designed for GraphQL. It handles the query/mutation body structure, operation naming, and variables automatically, so you do not need to manually construct the JSON payload.

For PactV3 and PactV2, there are two wrapper APIs available: GraphQLInteraction and ApolloGraphQLInteraction that can be used as a drop-in replacement for the addInteraction method. These are lightweight wrappers over the standard DSL to make GraphQL testing a bit nicer.

The addGraphQLInteraction() method provides a purpose-built builder for GraphQL queries and mutations.

Consumer Test​

import { Pact, Matchers, LogLevel } from '@pact-foundation/pact';

const { like } = Matchers;

const provider = new Pact({
  consumer: 'GraphQLConsumer',
  provider: 'GraphQLProvider',
  logLevel: 'info' as LogLevel,
});

describe('GraphQL consumer test', () => {
  it('queries for hello', async () => {
    const prepared = provider
      .addGraphQLInteraction()
      .given('the world exists')
      .uponReceiving('a hello request')
      .withOperation('HelloQuery')
      .withVariables({
        foo: 'bar',
      })
      .withRequest('POST', '/graphql')
      .withQuery(
        `
        query HelloQuery {
          hello
        }
        `
      )
      .willRespondWith(200, (builder) => {
        builder.headers({
          'Content-Type': 'application/json; charset=utf-8',
        });
        builder.jsonBody({
          data: {
            hello: like('Hello world!'),
          },
        });
      });

    await prepared.executeTest(async () => {
      // Call your GraphQL client pointing at the mock server
      const result = await myGraphQLClient.query({ query: HELLO_QUERY });
      expect(result.data.hello).to.equal('Hello world!');
    });
  });
});

The builder provides:

  • withOperation(name) — sets the GraphQL operation name
  • withVariables(vars) — sets the query variables
  • withQuery(query) — sets a GraphQL query (accepts a string or a graphql AST node)
  • withMutation(mutation) — sets a GraphQL mutation (accepts a string or a graphql AST node)

Use withQuery for read operations and withMutation for write operations. Each returns the standard HTTP interaction builder, so you chain willRespondWith and executeTest as normal.

Provider Verification​

Provider verification for GraphQL is identical to standard HTTP verification. Point the Verifier at your running GraphQL server:

import { Verifier, LogLevel } from '@pact-foundation/pact';

const opts = {
  pactUrls: ['./pacts/GraphQLConsumer-GraphQLProvider.json'],
  providerBaseUrl: 'http://localhost:4000/graphql',
  logLevel: 'info' as LogLevel,
};

new Verifier(opts).verifyProvider().then(() => {
  console.log('Pact Verification Complete!');
});

No special configuration is required on the provider side — GraphQL interactions are just HTTP POST requests.

Working Examples​

See the v4 GraphQL example for a complete runnable project, including both consumer and provider tests.

For PactV3 examples, see the v3 GraphQL example.