API Contract Testing: Pact, OpenAPI & Consumer-Driven Guide

Contract testing lets consumer and provider services verify compatibility independently — no shared environment, no end-to-end flakiness. This guide covers consumer-driven contracts with Pact, OpenAPI schema validation with schemathesis, and pipeline integration.

Contract Testing vs Integration Testing

Pact Consumer Test (Node.js / Jest)

The consumer defines the expected interaction. Pact spins up a mock provider, runs the consumer code against it, and saves the resulting contract as a JSON file:

// consumer.pact.test.ts
import { PactV3, MatchersV3 } from '@pact-foundation/pact';
import { getUserById } from '../api/usersClient';

const { like, string, integer } = MatchersV3;

const provider = new PactV3({
  consumer: 'orders-service',
  provider: 'users-service',
  port: 8080,
  dir: './pacts',  // contract files saved here
});

describe('Users Service contract', () => {
  it('returns a user by ID', async () => {
    await provider
      .given('user 42 exists')
      .uponReceiving('a request for user 42')
      .withRequest({
        method: 'GET',
        path: '/users/42',
        headers: { Authorization: like('Bearer token') },
      })
      .willRespondWith({
        status: 200,
        headers: { 'Content-Type': string('application/json') },
        body: {
          id: integer(42),
          name: string('Vic Chen'),
          email: string('[email protected]'),
        },
      })
      .executeTest(async (mockServer) => {
        const user = await getUserById(mockServer.url, '42');
        expect(user.id).toBe(42);
        expect(user.name).toBeDefined();
      });
  });
});
// After tests: ./pacts/orders-service-users-service.json is created

Pact Provider Verification

The provider loads contracts from the Pact Broker and verifies its real implementation satisfies every consumer's expectations:

// provider.pact.test.ts — run in the users-service CI pipeline
import { Verifier } from '@pact-foundation/pact';
import { app } from '../src/app';
import http from 'http';

describe('Pact Provider Verification', () => {
  let server: http.Server;
  let port: number;

  beforeAll(() => new Promise(resolve => {
    server = app.listen(0, () => {
      port = (server.address() as any).port;
      resolve(undefined);
    });
  }));

  afterAll(() => server.close());

  it('verifies all consumer contracts', async () => {
    await new Verifier({
      providerBaseUrl: `http://localhost:${port}`,
      pactBrokerUrl: process.env.PACT_BROKER_URL,
      pactBrokerToken: process.env.PACT_BROKER_TOKEN,
      provider: 'users-service',
      publishVerificationResult: true,
      providerVersion: process.env.GIT_SHA,
      // State handlers — set up test data per consumer scenario
      stateHandlers: {
        'user 42 exists': async () => {
          await db.users.upsert({ id: 42, name: 'Vic Chen', email: '[email protected]' });
        },
        'no users exist': async () => {
          await db.users.deleteAll();
        },
      },
    }).verifyProvider();
  });
});

OpenAPI Contract Testing with Schemathesis

Schemathesis generates hundreds of test cases from your OpenAPI spec and runs them against your live API, finding schema violations and crashes automatically:

# Install schemathesis
pip install schemathesis

# Test against a live staging API
schemathesis run https://staging-api.example.com/openapi.json \
  --checks all \
  --auth "Bearer $API_TOKEN" \
  --stateful=links \           # Follow OpenAPI link objects for stateful flows
  --max-examples=200 \         # Property-based test cases per endpoint
  --junit-xml=results.xml      # Output for CI

# Or test a local spec against a local server
schemathesis run ./openapi.yaml --url http://localhost:8080

# Example findings schemathesis catches:
# - 500 errors on valid inputs matching the spec
# - 200 responses with missing required fields
# - Accepting strings where the spec declares integer
# - Missing fields in error responses

# CI step in GitHub Actions
- name: API contract tests
  run: |
    schemathesis run $STAGING_URL/openapi.json \
      --auth "Bearer ${{ secrets.API_TOKEN }}" \
      --checks all \
      --junit-xml=schemathesis-results.xml
  continue-on-error: false