Contract Testing skill for Claude Code

A contract test proves that what a consumer expects and what a provider delivers still agree, without deploying both together. Done well, a provider cannot ship a change that breaks a deployed consumer, and each side tests in isolation in seconds.

Pick the approach

Situation	Approach
You own both sides; several internal consumers with different needs	Consumer-driven contracts (Pact)
Public or partner API with unknown consumers	Provider-owned OpenAPI spec + breaking-change diff + spec-conformance tests
Provider already has an accurate OpenAPI spec, consumers use Pact	Bi-directional (PactFlow) or validate consumer pacts against the spec
Async messages (Kafka, SQS events)	Pact message contracts, or a schema registry with compatibility rules
One team, one deploy unit	Not needed; use integration tests

Contracts test the shape and semantics of the interface, not business logic. Keep provider business rules in the provider’s own tests.

Workflow (Pact)

- [ ] 1. Identify consumer/provider pairs and who deploys independently
- [ ] 2. Write consumer tests against the Pact mock server
- [ ] 3. Publish pacts to a broker tagged with version and branch
- [ ] 4. Provider verifies pacts with state handlers
- [ ] 5. Gate deploys with can-i-deploy; record deployments
- [ ] 6. Add webhook so pact changes trigger provider verification

2. Consumer test (pact-js, V4 API)

import path from 'node:path';
import { PactV4, MatchersV3 } from '@pact-foundation/pact';
import { OrdersClient } from '../src/orders-client';

const { integer, string, eachLike, datetime } = MatchersV3;
const pact = new PactV4({ consumer: 'web-app', provider: 'orders-api', dir: path.resolve('pacts') });

describe('OrdersClient', () => {
  it('fetches an existing order', async () => {
    await pact
      .addInteraction()
      .given('order 42 exists')
      .uponReceiving('a request for order 42')
      .withRequest('GET', '/orders/42', (b) => b.headers({ Accept: 'application/json' }))
      .willRespondWith(200, (b) =>
        b.jsonBody({
          id: integer(42),
          status: string('paid'),
          createdAt: datetime("yyyy-MM-dd'T'HH:mm:ssX", '2026-01-05T10:00:00Z'),
          items: eachLike({ sku: string('A-1'), qty: integer(1) }),
        }))
      .executeTest(async (mock) => {
        const order = await new OrdersClient(mock.url).getOrder(42);
        expect(order.status).toBe('paid');
      });
  });
});

Consumer rules:

• Exercise the real client code, not raw fetch, so the pact reflects actual usage.
• Use type matchers (integer, string, eachLike) rather than exact values, so the provider can return any valid data.
• Include only fields the consumer actually reads. Extra provider fields are fine; a pact that lists every field blocks harmless provider changes.
• Cover the error responses the consumer handles (404, 422), each with its own state.
• Provider state names are a shared vocabulary: order 42 exists, not setup1.

Other languages have equivalent DSLs (pact-jvm, pact-python, pact-go, pact-net); follow the same structure.

3. Publish

pact-broker publish ./pacts \
  --consumer-app-version "$GIT_SHA" \
  --branch "$GIT_BRANCH" \
  --broker-base-url "$PACT_BROKER_BASE_URL" \
  --broker-token "$PACT_BROKER_TOKEN"

The CLI ships in the pactfoundation/pact-cli Docker image and the @pact-foundation/pact-cli npm package. Always version by commit SHA, never by a semver that repeats across commits.

4. Provider verification

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

await new Verifier({
  provider: 'orders-api',
  providerBaseUrl: 'http://localhost:8080',
  pactBrokerUrl: process.env.PACT_BROKER_BASE_URL,
  pactBrokerToken: process.env.PACT_BROKER_TOKEN,
  providerVersion: process.env.GIT_SHA,
  providerVersionBranch: process.env.GIT_BRANCH,
  publishVerificationResult: process.env.CI === 'true',
  consumerVersionSelectors: [{ mainBranch: true }, { deployedOrReleased: true }, { matchingBranch: true }],
  enablePending: true,
  stateHandlers: {
    'order 42 exists': async () => { await db.orders.insert(orderFixture({ id: 42, status: 'paid' })); },
  },
}).verifyProvider();

• Run the real provider app with real routing and serialization; stub only its own downstream dependencies.
• State handlers set up data directly (DB insert or repository fake), not via other APIs.
• enablePending: true lets new consumer expectations fail without breaking the provider build until the provider has passed them once.
• Only publish verification results from CI.

5. Deploy gate

pact-broker can-i-deploy --pacticipant web-app --version "$GIT_SHA" \
  --to-environment production --retry-while-unknown 6 --retry-interval 10
# after a successful deploy:
pact-broker record-deployment --pacticipant web-app --version "$GIT_SHA" --environment production

Both consumer and provider pipelines run can-i-deploy before deploying and record-deployment after. Without record-deployment, the broker cannot know what is in production and the deployedOrReleased selector verifies nothing.

Broker setup, webhooks, and the full CI flow are in references/pact-broker-flow.md; read it when wiring pipelines for the first time.

Workflow (OpenAPI schema contracts)

- [ ] 1. Make the spec the source of truth (generated from code or code generated from spec)
- [ ] 2. Lint the spec (Spectral or Redocly)
- [ ] 3. Validate real responses against the spec in provider tests
- [ ] 4. Fail PRs on breaking spec changes with oasdiff
- [ ] 5. Fuzz the running API against the spec with Schemathesis

# breaking-change gate in CI (base spec from main, head spec from the PR)
oasdiff breaking main-openapi.yaml openapi.yaml --fail-on ERR

# property-based conformance against a running instance
schemathesis run http://localhost:8080/openapi.json

In provider tests, assert each response conforms to the spec, e.g. with jest-openapi (expect(res).toSatisfyApiSpec()) in JS or openapi-core in Python. A spec that is not checked against real responses drifts within weeks.

Gotchas

• Contracts written by the provider team “for” consumers are not consumer-driven; they test what the provider thinks is used.
• Exact-value matching in pacts creates failures on any data change. Use matchers.
• Sharing one provider state that sets up everything makes states order-dependent and slow.
• Pact verifies HTTP shape, not auth flows; stub auth in verification with a known token or a request filter, and test auth separately.
• Breaking changes that are schema-compatible still break: changing the meaning of a field, new enum values the consumer does not handle. Treat new enum values as breaking unless consumers are documented to ignore unknowns.
• can-i-deploy without --to-environment (or with stale tags) checks the wrong matrix.

Verification

1. Introduce a deliberate break in the provider (rename a field a consumer reads) and confirm provider verification fails and can-i-deploy returns non-zero.
2. Add an unused field in the provider and confirm nothing fails.
3. For OpenAPI, delete a required response property in the spec on a branch and confirm oasdiff breaking fails the PR.