Contract Testing with Pact

By Khimananda Oli | Last reviewed: August 2026

Integration failures remain the primary cause of production incidents in microservice architectures, often stemming from uncoordinated API changes between teams. Contract testing with Pact solves this by validating that a consumer's expectations match a provider's actual implementation before code merges, eliminating the need for fragile end-to-end test environments. This approach shifts integration verification left into your CI pipeline, providing fast feedback and enabling independent deployments without sacrificing reliability.

What is contract testing with Pact and why does it matter?

In traditional microservice development, teams rely heavily on end-to-end (E2E) tests running against a shared staging environment to catch integration issues. In practice, these environments are slow, flaky, and expensive to maintain. When Team A updates an API response field and Team B’s frontend breaks three days later in staging, you have already wasted significant engineering time. CI/CD best practices for small teams emphasize shifting quality checks left, and contract testing is the most effective mechanism for doing so at the integration boundary.

Pact implements Consumer-Driven Contracts (CDC). Instead of the provider dictating the API specification in isolation, the consumer writes tests describing exactly what it needs from the provider. These tests generate a "pact file" (a JSON contract). The provider then runs a verification test against this contract to prove it meets the consumer's needs. If the provider changes its API in a way that violates the contract, the provider's build fails immediately, not days later in a shared environment.

This model fundamentally changes how teams coordinate. You no longer need to spin up the entire ecosystem to test a single service change. For teams managing complex architectures, perhaps following guidance on deploying apps to Kubernetes clusters, this reduction in environmental dependencies translates directly to faster release cycles and lower infrastructure costs.

How do you write consumer tests and generate pact files?

The consumer side of contract testing with Pact defines the interface from the perspective of usage. You are not testing the provider's logic; you are documenting your requirements. Using the JavaScript/TypeScript ecosystem as an example (though Pact supports JVM, Go, Python, .NET, and others), the setup involves defining an interaction and executing the client code against a mock server.

Defining the interaction

A common mistake is treating contract tests like unit tests for business logic. They are not. They are strict specifications of HTTP communication. Keep interactions focused on one request-response pair per test case.

import { PactV3, MatchersV3 } from '@pact-foundation/pact';
import { getUserById } from './userService';

const provider = new PactV3({
  consumer: 'FrontendApp',
  provider: 'UserAPI',
});

describe('Get User by ID', () => {
  it('returns a valid user object when user exists', async () => {
    const expectedUser = {
      id: MatchersV3.integer(1),
      name: MatchersV3.string('Khimananda'),
      email: MatchersV3.regex(/[\\w.]+@[\\w.]+/, '[email protected]')
    };

    await provider
      .given('a user with ID 1 exists')
      .uponReceiving('a request for user 1')
      .withRequest({ method: 'GET', path: '/users/1' })
      .willRespondWith({ status: 200, body: expectedUser });

    return provider.executeTest(async (mockserver) => {
      const user = await getUserById(mockserver.url, 1);
      expect(user.name).toEqual('Khimananda');
    });
  });
});

Note the use of MatchersV3. Hardcoding values like specific UUIDs or timestamps creates brittle contracts. Matchers allow flexibility while enforcing structure. The given() clause defines a provider state, which is critical for setting up test data on the provider side during verification without coupling the consumer to the provider's database schema.

Generating and publishing the contract

After running the test suite, Pact generates a JSON file in the pacts/ directory. This file must be published to a Pact Broker. Never share pact files via artifacts or git repositories in production workflows; the Broker provides versioning, tagging, and matrix tracking essential for determining compatibility across multiple service versions.

• Tag consumer pacts with branch names (e.g., main, feat/new-dashboard) and semantic versions.
• Use the pact-broker-client CLI or CI plugin to publish immediately after successful tests.
• Enable "WIP Pacts" in the Broker to allow development branches to verify against providers without blocking main builds.

How does provider verification work in a CI pipeline?

The provider verification step is where contract testing with Pact delivers its safety guarantee. Unlike the consumer side, which uses mocks, the provider side spins up the real application (or a representative slice of it) and replays the requests defined in the pact file against it.

Handling provider states

When the consumer specifies given('a user with ID 1 exists'), the provider must interpret this string and configure its environment accordingly. This is typically done via a state handler map or webhook. Do not skip this step. Without proper state setup, provider verification becomes a test of whether your database happens to have leftover data from previous runs.

// Example state handler in Node.js provider verifier
const stateHandlers = {
  'a user with ID 1 exists': async () => {
    await db.users.upsert({ 
      id: 1, 
      name: 'Khimananda', 
      email: '[email protected]' 
    });
  },
  'no users exist': async () => {
    await db.users.truncate();
  }
};

const verifier = new Verifier({
  providerBaseUrl: 'http://localhost:3000',
  pactBrokerUrl: process.env.PACT_BROKER_URL,
  stateHandlers: stateHandlers,
  publishVerificationResult: true,
  providerVersion: process.env.GIT_SHA,
  providerBranch: process.env.BRANCH_NAME
});

await verifier.verifyProvider();

For teams integrating this into broader automation strategies, aligning verification steps with your chosen CI/CD platform ensures consistent feedback loops regardless of whether you use GitHub Actions, GitLab CI, or Jenkins.

Contract testing with Pact vs end-to-end testing: which should you use?

A frequent question from engineering leads is whether contract testing replaces E2E tests entirely. The answer is no, but it drastically reduces the scope and volume required. Understanding the trade-offs helps allocate testing budget effectively.

Use contract testing with Pact to validate 90% of integration points. Reserve E2E tests for critical user journeys that span multiple domains or involve browser-specific behavior. If your E2E suite takes over 30 minutes or fails more than 5% of the time due to non-bug causes, migrate those checks to contracts first.

How do you manage breaking changes and version compatibility?

The true power of the Pact Broker emerges when managing multiple concurrent versions. In production systems, especially those serving mobile clients or third-party integrators, you cannot always force simultaneous upgrades. The Broker tracks which consumer versions are compatible with which provider versions through a verification matrix.

Using "Can I Deploy?"

Before deploying any service, query the Broker to confirm compatibility with currently deployed peers. This check should be a mandatory gate in your deployment pipeline.

# Check if Provider v2.4.0 can deploy to production
# alongside Consumer v1.8.0 (currently in prod)
pact-broker can-i-deploy \
  --pacticipant UserAPI --version 2.4.0 \
  --to-environment production \
  --retry-while-unknown=6 \
  --retry-interval=10

If the command returns false, the deployment halts. This prevents the scenario where a provider deploys a breaking change that hasn't been verified against the live consumer version yet. For teams operating in regulated environments or handling sensitive data, this automated compatibility check serves as evidence for compliance audits, complementing infrastructure controls discussed in guides on secrets management with HashiCorp Vault.

Backward compatibility strategies

When a breaking change is unavoidable, use the Broker's branching and tagging features to manage the transition. Deploy the new provider version tagged as next while maintaining the current production tag. Consumers migrate at their own pace, verifying against the next tag during their development cycle. Only promote the new provider to production once all active consumers have verified compatibility. This pattern eliminates coordinated deployment windows and reduces operational risk significantly.

Implementing contract testing with Pact in your workflow

Adopting contract testing with Pact requires discipline but yields compounding returns. Start with your most painful integration point—typically the service causing the most staging failures or deployment delays. Instrument the consumer first, establish the Broker, then add provider verification. Resist the urge to retrofit every existing API immediately; let adoption spread organically as teams experience the speed benefits.

Remember that contracts are living documentation. Treat them with the same rigor as production code. Review pact files during pull requests, enforce matcher usage over hardcoded values, and monitor verification trends in the Broker dashboard. When integrated properly, this practice transforms integration from a bottleneck into a non-event, allowing your team to focus on delivering value rather than debugging environment drift.

If your team is struggling with integration reliability or needs help designing a testing strategy that scales with your architecture, reach out to discuss your specific challenges. Practical, security-first DevOps guidance can turn fragile pipelines into predictable delivery engines.