Contract testing bridges the gap between unit tests and full integration tests by verifying that services can communicate correctly without requiring all services to be running simultaneously. Consumer-driven contract testing, pioneered by the Pact framework, inverts the traditional approach: consumers define what they expect from providers, and providers verify they can satisfy those expectations. This skill guides AI coding agents through generating robust contract tests that catch integration breaking changes before they reach production.
Core Principles
Consumer-Driven Design: Consumers define the contract based on what they actually use, not what the provider offers. This ensures contracts are minimal, focused, and reflect real usage patterns rather than hypothetical API surfaces.
Provider Verification Independence: Provider tests verify contracts independently without needing the consumer running. This decouples deployment schedules and enables teams to work autonomously while maintaining integration guarantees.
Contract as Shared Artifact: The contract (pact file) serves as a living specification between consumer and provider. It is versioned, stored centrally, and referenced by both sides during their respective CI pipelines.
Minimal Assertion Surface: Contracts should assert only what the consumer needs, not the full provider response. Testing for specific fields rather than entire response bodies prevents brittle contracts that break on harmless provider changes.
Versioning Alignment with Deployability: Every contract must be associated with a specific consumer version and verified against a specific provider version. The combination of these versions determines whether a deployment is safe.
Fail-Fast in CI: Contract verification failures must block deployments. The can-i-deploy tool provides a definitive answer about deployment safety based on the latest verification matrix.
Incremental Adoption: Contract tests can be introduced for the most critical interactions first, then expanded. There is no requirement to cover every endpoint immediately; focus on high-risk integration points.
Pending pacts prevent new consumers from breaking existing provider builds. WIP (Work in Progress) pacts allow verification of contracts from feature branches.
// provider/pact-config.tsexportconst providerVerificationConfig = {
// Pending pacts: new contracts won't fail the provider build// Once a pact is successfully verified, it transitions out of pendingenablePending: true,
// WIP pacts: include pacts from consumer feature branches// Only pacts published after this date are consideredincludeWipPactsSince: '2024-01-01',
// Consumer version selectors determine which pacts to verifyconsumerVersionSelectors: [
{ mainBranch: true }, // Pacts from consumers' main branch
{ deployedOrReleased: true }, // Pacts from currently deployed consumers
{ matchingBranch: true }, // Pacts from same-named feature branch
{ branch: 'develop' }, // Always verify develop branch pacts
],
};
Bi-Directional Contract Testing
Bi-directional contract testing allows providers to publish their own OpenAPI specification rather than running consumer pact tests directly. The Pact Broker compares the consumer pact with the provider specification.
{"scripts":{"test:contract:consumer":"jest --testPathPattern=consumer.pact","test:contract:provider":"jest --testPathPattern=provider-verification","pact:publish":"ts-node scripts/publish-pacts.ts","pact:can-i-deploy":"bash ci/can-i-deploy.sh","pact:broker":"docker compose -f pact-broker/docker-compose.yml up -d"}}
Best Practices
Use Pact matchers instead of exact values. Matchers like like(), regex(), and eachLike() validate structure and type rather than specific values, making contracts resilient to data changes.
Keep provider states minimal and descriptive. Each given() state should describe a precondition clearly (e.g., "a user with ID 42 exists") and the state handler should set up only what is needed.
Version pacts with git commit SHA. Using the git commit SHA as the consumer version ensures traceability and enables the can-i-deploy tool to accurately determine deployment safety.
Enable pending pacts in provider verification. This prevents new consumers or new interactions from immediately breaking the provider build while still tracking verification status.
Run can-i-deploy before every deployment. This is the single most important practice for preventing integration breakages; it should gate every production deployment.
Test only what the consumer uses. If the consumer only reads the id and name fields from a 20-field response, the contract should only assert on those two fields.
Use consumer version selectors wisely. Always verify pacts from mainBranch and deployedOrReleased; add matchingBranch for feature branch coordination between teams.
Publish verification results from CI only. Set publishVerificationResult: true only when running in CI to avoid polluting the broker with local verification results.
Implement proper state handlers. Provider state handlers should seed the database or configure mocks to satisfy each consumer expectation reproducibly.
Tag environments with record-deployment. After successful deployment, record the deployment in the broker so can-i-deploy knows which versions are in which environments.
Include request headers in contracts when they affect behavior. If the provider returns different responses based on Accept headers or API versions, include those in the contract.
Use separate CI jobs for consumer and provider. Consumer tests and provider verification should run independently, connected only through the Pact Broker.
Anti-Patterns to Avoid
Asserting on entire response bodies. Never match every field in a provider response. This creates brittle contracts that break when the provider adds a new field, which should be a non-breaking change.
Using exact matchers for dynamic data. Dates, IDs, and timestamps should use type matchers or regex matchers, not exact values. Using like(42) is correct; using the literal 42 is fragile.
Sharing a single provider state across unrelated tests. Each test should declare its own provider state. Reusing states like "default state" leads to hidden coupling and test fragility.
Running provider verification against a shared staging environment. Provider verification must run against a locally started provider instance to ensure reproducibility and speed.
Skipping can-i-deploy because it is slow. If can-i-deploy is too slow, configure retry parameters rather than bypassing it. The --retry-while-unknown flag handles asynchronous verification gracefully.
Coupling consumer and provider test suites. Consumer and provider tests must live in their respective repositories. The pact file (or broker) is the only connection between them.
Using contract tests as functional tests. Contract tests verify the shape and structure of interactions, not business logic. Do not test complex business scenarios through contracts.
Debugging Tips
Enable verbose logging. Set logLevel: 'debug' in the Pact configuration or use the environment variable PACT_LOG_LEVEL=debug to see detailed request/response matching output.
Inspect generated pact files. The JSON pact files in the output directory contain the exact interactions defined. Reviewing these files helps identify matcher misconfigurations before publishing.
Use the Pact Broker UI. The broker provides a visual matrix showing which consumer versions are verified against which provider versions. This is invaluable for diagnosing can-i-deploy failures.
Check provider state handler execution. If verification fails with unexpected data, add logging to state handlers to confirm they execute and set up data correctly.
Verify the mock server URL. A common failure is the consumer test using a hardcoded URL instead of mockServer.url. Always construct the API client with the dynamic mock server URL.
Compare pact specification versions. If consumer and provider use different Pact specification versions (v2 vs v3 vs v4), certain matchers may not be supported. Align on the same specification version.
Check for port conflicts. When running multiple Pact tests in parallel, ensure each test uses a unique port or let Pact assign random ports automatically.
Validate webhook configuration. If provider verification does not trigger after pact publication, check the broker webhook configuration and review the webhook execution logs in the broker UI.
Review the verification output diff. When provider verification fails, the output shows an expected vs actual diff. Focus on the specific field or header that mismatched rather than the entire interaction.
Test state handlers in isolation. Before running full verification, run state handler functions independently to confirm they produce the expected database state or mock configuration.
