api-contract-testing

API Contract Testing

CONSUMER-DRIVEN CONTRACT TESTING INVERTS THE TRADITIONAL INTEGRATION TEST — EACH CONSUMER PUBLISHES THE EXACT SHAPE IT EXPECTS, THE PROVIDER VERIFIES AGAINST EVERY CONSUMER'S CONTRACT IN CI, AND A BREAKING CHANGE IS CAUGHT THE MOMENT IT IS INTRODUCED INTO THE PROVIDER CODEBASE RATHER THAN DISCOVERED AT DEPLOYMENT TIME WHEN ROLLING BACK COSTS HOURS.

When to Use

• Adding a new API consumer (frontend, mobile, partner service) and formalizing what shape it expects from the provider
• Running a provider code change through CI and needing proof that no existing consumer contract is broken before merging
• Integrating spectral or vacuum schema linting into a CI pipeline for an OpenAPI spec that has no automated quality gate today
• Evaluating oasdiff or openapi-diff for automated breaking-change detection between two versions of a spec
• Replacing a brittle end-to-end integration test suite with faster, isolated contract tests that do not require a live environment
• Writing the API governance checklist for a platform team that ships multiple versioned services
• Onboarding a new team to consumer-driven contract practices before they begin building their first provider

Instructions

Key Concepts

1. Consumer-driven contracts — A consumer-driven contract captures the exact subset of the provider API that a specific consumer uses: the request shape it sends and the minimum response fields it requires. The consumer publishes this contract as a Pact file (JSON); the provider runs the Pact file against its real implementation in CI. If the provider's response no longer satisfies the consumer's contract, the provider build fails — before any deployment. This is the inverse of provider-driven testing, where the provider defines what it thinks consumers need and consumers adapt. Consumer-driven contracts give each consumer a voice in breaking-change detection.

2. Pact fundamentals — A Pact file is a JSON document that encodes one or more interactions: { "description": "a request for payment intent pi_xxx", "request": { "method": "GET", "path": "/payment_intents/pi_xxx" }, "response": { "status": 200, "body": { "id": "pi_xxx", "status": "succeeded" } } }. The consumer writes the test using the Pact DSL (available in JavaScript, Python, Go, Java, Ruby, .NET); the DSL generates the Pact file and runs a mock provider during the consumer test. The provider test replays each interaction from the Pact file against the real provider, verifying response status, headers, and body match the consumer's expectations.