pact-contract-testing

Overview

Pact is a code-first tool for testing HTTP and message integrations using consumer-driven contract tests (pact-overview). The contract is generated as a side-effect of the consumer's automated tests - each test case documents one request/response pair, and only the parts the consumer actually uses get tested.

The full lifecycle has five steps (pact-how-it-works):

1. Consumer test runs against a Pact mock server using the Pact DSL.
2. The Pact framework writes a pact file (JSON) capturing every given() → uponReceiving() → withRequest() → willRespondWith() interaction.
3. The pact file is published to the Pact Broker.
4. The provider verifies the pact: each request from the file is replayed against the actual provider, and responses are checked against the contract.
5. can-i-deploy queries the Broker's matrix to confirm the candidate version has a green verification against every consumer/ provider already deployed in the target environment (can-i-deploy).

When to use

• Two or more services communicate over HTTP/JSON or a message bus.
• The team owns both consumer and provider (or has access to the provider team) - Pact requires provider buy-in for verification.
• A team wants a deployment safety net richer than schema-only comparison: contract-by-example asserts what consumers actually use, not the full provider surface.
• The repo already imports @pact-foundation/pact, pact-jvm-consumer, pact-python, etc., or a .pact/ directory is present.

If the API has no consumers under your control (public APIs, third-party integrations), prefer openapi-contract-diff - schema- based diffs need no provider/consumer coordination.

Authoring (consumer side)

Install (Node example)

npm install --save-dev @pact-foundation/pact

(Per pact-js.)

Consumer test with PactV3

const { PactV3, MatchersV3 } = require('@pact-foundation/pact');
const { like, eachLike } = MatchersV3;

const provider = new PactV3({
  consumer: 'web-app',
  provider: 'pet-service',
  dir: path.resolve(process.cwd(), 'pacts'),
});

describe('Pet Service consumer', () => {
  it('returns a list of dogs', async () => {
    provider
      .given('I have a list of dogs')
      .uponReceiving('a request for all dogs with the builder pattern')
      .withRequest({
        method: 'GET',
        path: '/dogs',
        headers: { Accept: 'application/json' },
      })
      .willRespondWith({
        status: 200,
        headers: { 'Content-Type': 'application/json' },
        body: eachLike({
          id: like(1),
          name: like('Rex'),
        }),
      });

    await provider.executeTest(async (mockServer) => {
      const response = await fetch(`${mockServer.url}/dogs`);
      expect(response.status).toBe(200);
    });
  });
});

(Adapted from pact-js.)

The DSL lifecycle is given() → uponReceiving() → withRequest() → willRespondWith(). given() describes a provider state the verifier will set up later. Matchers like like() and eachLike() let the contract assert type/shape rather than exact values, so the provider isn't bound to fixture-specific data.

Where pact files are written

By default, PactV3 writes pact files to ./pacts/ relative to the process CWD (pact-js). Each consumer/provider pair produces one JSON file: <consumer>-<provider>.json.

Publishing to the Pact Broker

The Broker is the central registry for pact files and verification results. Publishing happens after the consumer tests pass:

npx pact-broker publish ./pacts \
  --consumer-app-version=$(git rev-parse HEAD) \
  --branch=$(git rev-parse --abbrev-ref HEAD) \
  --broker-base-url=$PACT_BROKER_BASE_URL \
  --broker-token=$PACT_BROKER_TOKEN

The Broker stores (overview):

• The pact files themselves.
• Provider verification results per consumer version.
• Tags and branches that map app versions to lifecycle environments (e.g. production, staging, main).

Tagging by branch + the Git SHA as consumer-app-version is the canonical pattern - can-i-deploy queries the matrix using these identifiers.

Provider verification

const { Verifier } = require('@pact-foundation/pact');

new Verifier({
  providerBaseUrl: 'http://localhost:8081',
  pactBrokerUrl: process.env.PACT_BROKER_BASE_URL,
  pactBrokerToken: process.env.PACT_BROKER_TOKEN,
  provider: 'pet-service',
  providerVersion: process.env.GIT_SHA,
  providerVersionBranch: process.env.GIT_BRANCH,
  publishVerificationResult: true,
  consumerVersionSelectors: [
    { mainBranch: true },
    { deployedOrReleased: true },
  ],
}).verifyProvider();

(Adapted from pact-js.)

The provider replays every request from each pact file against a running provider instance and compares responses (pact-how-it-works). consumerVersionSelectors controls which consumer pacts get verified - mainBranch plus deployedOrReleased ensures the provider stays compatible with both the latest consumer work and what's currently in production.

publishVerificationResult: true is what makes the matrix update - without it, the broker has no record of this provider version's verification status.

Provider states

For each consumer interaction with a given(<state>), the provider test setup must register a hook that puts the system into that state before replay. Using Express:

new Verifier({
  ...
  stateHandlers: {
    'I have a list of dogs': async () => {
      await db.dogs.bulkInsert([{ id: 1, name: 'Rex' }]);
      return { description: 'dogs seeded' };
    },
  },
}).verifyProvider();

State setup that fails causes the matching interaction to fail verification.

can-i-deploy - deployment gate

Per can-i-deploy:

pact-broker can-i-deploy \
  --pacticipant pet-service \
  --version $(git rev-parse HEAD) \
  --to-environment production

Exit codes (can-i-deploy):

• 0 - "Computer says yes \o/" - safe to deploy.
• 1 - "Computer says no" - at least one matrix cell is missing or failed.

The output includes a markdown-style matrix of consumer/provider version pairs with verification status and links to detailed verification results.

Recording deployments

After deploying, record the deployment so subsequent can-i-deploy queries see the new "currently deployed" baseline:

pact-broker record-deployment \
  --pacticipant pet-service \
  --version $(git rev-parse HEAD) \
  --environment production

Skipping this step is the most common reason can-i-deploy returns spurious "no" verdicts.

CI integration

A complete CI flow per side:

Consumer pipeline

- name: Run consumer tests + publish pact
  env:
    PACT_BROKER_BASE_URL: ${{ secrets.PACT_BROKER_BASE_URL }}
    PACT_BROKER_TOKEN:    ${{ secrets.PACT_BROKER_TOKEN }}
  run: |
    npm test                           # writes ./pacts/<consumer>-<provider>.json
    npx pact-broker publish ./pacts \
      --consumer-app-version=$GITHUB_SHA \
      --branch=${GITHUB_REF##*/}

- name: Can I deploy?
  env:
    PACT_BROKER_BASE_URL: ${{ secrets.PACT_BROKER_BASE_URL }}
    PACT_BROKER_TOKEN:    ${{ secrets.PACT_BROKER_TOKEN }}
  run: |
    pact-broker can-i-deploy \
      --pacticipant=web-app \
      --version=$GITHUB_SHA \
      --to-environment=production

Provider pipeline

- name: Verify pacts from broker
  env:
    PACT_BROKER_BASE_URL: ${{ secrets.PACT_BROKER_BASE_URL }}
    PACT_BROKER_TOKEN:    ${{ secrets.PACT_BROKER_TOKEN }}
  run: |
    npm run start:provider &
    npx wait-on http://localhost:8081
    npm run verify:pact                # publishVerificationResult: true

- name: Can I deploy?
  env:
    PACT_BROKER_BASE_URL: ${{ secrets.PACT_BROKER_BASE_URL }}
    PACT_BROKER_TOKEN:    ${{ secrets.PACT_BROKER_TOKEN }}
  run: |
    pact-broker can-i-deploy \
      --pacticipant=pet-service \
      --version=$GITHUB_SHA \
      --to-environment=production

can-i-deploy is the actual gate - pact verification happens in step 1, but a green verification alone doesn't prove every paired version is compatible.

References

• pact-overview - what Pact is, contract-by-example.
• pact-how-it-works - consumer / provider / broker lifecycle.
• pact-js - Node SDK install + PactV3 DSL + Verifier setup.
• can-i-deploy - the deployment-gate CLI.