graphql-contract

graphql-contract

Consumer-driven contract testing for GraphQL APIs using field selection sets. Frontend teams declare which fields they consume; backend CI fails if those fields change incompatibly. No Pact Broker server required — contracts are simple JSON files stored alongside your code.

Installation

npm install graphql-contract --save-dev
# graphql is a peer dependency
npm install graphql

Quick Start

Consumer Side

In your frontend/consumer project, define and publish a contract:

import { defineContract, publishContract } from 'graphql-contract';

const contract = defineContract({
  consumer: 'web-app',
  provider: 'user-service',
  operations: [
    `query GetUser {
      user(id: "1") {
        id
        email
        name
      }
    }`,
    `query GetUsers {
      users {
        id
        name
      }
    }`,
  ],
});

await publishContract(contract, {
  outputPath: './contracts/web-app.json',
});

Provider Side

In your backend/provider project, verify contracts against your schema:

import { buildSchema } from 'graphql';
import { verifyContracts } from 'graphql-contract';

const schema = buildSchema(`
  type Query {
    user(id: ID!): User!
    users: [User!]!
  }

  type User {
    id: ID!
    email: String!
    name: String!
  }
`);

const result = await verifyContracts({
  schema,
  contractsPath: './contracts',
});

if (!result.passed) {
  console.error('Contract violations found:');
  for (const v of result.violations) {
    console.error(`  ${v.field}: ${v.reason}`);
  }
  process.exit(1);
}

console.log('All contracts verified successfully.');

API Reference

defineContract(opts)

Creates a contract object.

Parameter	Type	Description
opts.consumer	string	Name of the consuming service
opts.provider	string	Name of the provider service
opts.operations	string[]	GraphQL operation strings

Returns a GraphQLContract object. Throws if any operation is syntactically invalid GraphQL.

publishContract(contract, opts)

Writes a contract to a JSON file.

Parameter	Type	Description
contract	GraphQLContract	The contract to publish
opts.outputPath	string	File path to write the JSON contract

verifyContracts(opts)

Verifies all contract JSON files in a directory against a GraphQL schema.

Parameter	Type	Description
opts.schema	GraphQLSchema	The provider's GraphQL schema
opts.contractsPath	string	Path to directory containing contract JSON files

Returns { passed: boolean; violations: ContractViolation[] }.

checkOperationCompatibility(operation, schema)

Low-level check for a single operation against a schema.

Parameter	Type	Description
operation	string	A GraphQL operation string
schema	GraphQLSchema	The schema to check against

Returns ContractViolation[].

How It Fits Into CI

• Consumer CI: Run defineContract + publishContract to generate contract JSON files. Commit them to the provider repo or a shared contracts repo.

• Provider CI: Run verifyContracts against your current schema. If any violations are found, the build fails before deployment.

# Example GitHub Actions step (provider)
- name: Verify GraphQL contracts
  run: npx tsx scripts/verify-contracts.ts

This ensures backend teams cannot accidentally break fields that frontend teams depend on.

License

MIT