Published
API Contract Testing: How It Works, Tools and a Starter Setup
Short answer
API contract testing checks that an API provider and the clients that call it agree on the shape of requests and responses, without running both services together. In consumer-driven contract testing, each consumer records what it needs, and the provider replays those expectations in its own build. In schema-based contract testing, the provider is checked against its OpenAPI document. Both catch breaking API changes before deployment.
Last updated: 2026-11-13
What is API contract testing?
A contract is the agreement between a consumer (a client that wants data) and a provider (the API that serves it): which requests are valid and what comes back. Contract testing verifies that both sides still honor that agreement.
The Pact documentation points out that the term is used in two ways. In integration contract testing, the focus is the pair of services: does the consumer call the provider correctly, and can the provider meet what the consumer expects? In provider contract testing, the focus is a single provider: does its real behavior conform to its documented contract, such as an OpenAPI file? Pact notes that the second kind, on its own, gives no test-based assurance that consumers call the provider correctly or that the provider meets all of its consumers' expectations.
How does consumer-driven contract testing work?
Pact is the best-known code-first tool for consumer-driven contracts. Its documentation describes this flow:
- The consumer writes a unit test of its API client against a mock provided by Pact.
- Pact writes the interactions from that test into a contract file, a JSON document called a pact.
- The consumer publishes the pact to a broker, or shares the file another way.
- Pact retrieves the pact and replays each request against a locally running provider.
- The provider's real responses are compared with the minimal responses the consumer expected.
Because the contract comes from what consumers actually use, only the parts of the API that are used get tested. Pact's docs state that provider behavior no consumer uses is free to change without breaking tests. Neither side needs the other running, so the tests are fast and the failures point to one interaction.
Pact's own guidance on writing consumer tests is worth following: treat them as good unit tests for your API client, test the actual client code, and use loose matching (types and regular expressions) where exact values would make tests brittle. It also says to use Pact for contract testing, not functional testing of the provider. Ask whether removing a given test could let a real provider change break the consumer unnoticed; if not, the test is unnecessary.
What is provider verification and can-i-deploy?
Provider verification is the provider-side half. In Pact JS and other implementations, the verifier takes pacts from a broker URL or a list of file paths, replays them against the running provider, and can publish the results so consumers can see them. If a consumer test used a provider state such as "User 1234 exists", the verifier calls a state handler you write to put the provider in that state first.
The Pact Broker CLI includes can-i-deploy. Pact's docs describe it as giving a definitive answer on whether the version you are about to deploy is compatible with the versions of the services it talks to. Run it as a CI step before each deployment. Pact also documents pending pacts, which let consumers publish new or changed contracts without immediately failing the provider's build.
When you must make a breaking change, Pact's FAQ recommends an expand-and-contract sequence: add the new fields or endpoints to the provider and deploy, move consumers across, then remove the old ones. Contract tests stay green at every step.
How does OpenAPI contract testing differ?
If you have an OpenAPI document, you can test the provider against it directly. Schemathesis generates property-based tests from OpenAPI and GraphQL schemas, and its docs list support for OpenAPI 2.0, 3.0, 3.1 and 3.2. It produces schema examples, valid data that follows constraints, and invalid data that breaks them, and it can chain operations into stateful sequences. Its FAQ contrasts this with Dredd, saying Schemathesis aims to find unexpected edge cases instead of only checking documented examples.
This answers "does the API do what the spec says?" It does not answer "does the client call it the way the API expects?" For that you need the consumer's side. Teams with many consumers often use both: schema checks on the provider for conformance and consumer-driven pacts for the integration.
| Consumer-driven (Pact) | Schema-based (OpenAPI) | |
|---|---|---|
| Source of truth | Consumer tests | The OpenAPI document |
| Tests what | What consumers actually use | Everything the spec describes |
| Catches | Breaking changes that hit a real consumer | Drift between code and docs, edge-case failures |
| Needs | Consumer team to write pact tests | An accurate, maintained spec |
| Best for | Internal services with known consumers | Public APIs and many unknown consumers |
How is contract testing different from integration and end-to-end tests?
Contract tests replace the integration part of broad end-to-end tests with small, fast checks of one interaction. Pact's FAQ lists replacing the integration testing aspects of end-to-end tests with contract tests as a step toward faster feedback.
They do not replace end-to-end tests. A contract test proves a response has the agreed shape. It does not prove the signup flow works in a browser, that the right email goes out, or that a payment completes. Keep a small number of end-to-end tests on the flows that matter most, and let contracts guard the seams between services. See flaky tests for why trimming the end-to-end layer pays off.
A starter setup for a small team
You do not need a service mesh to benefit. For two services owned by one team:
- Pick the one integration that has broken before, such as the web app calling the orders API.
- Write consumer tests for the API client covering the three or four calls it makes, using type-based matchers.
- Run provider verification in the orders API build, with state handlers that seed the data each scenario needs.
- Publish pacts to a broker (a hosted one or self-hosted) and add
can-i-deployto the deploy job. - If a public OpenAPI file exists, add a nightly Schemathesis run against a staging copy.
- Add the contract job to your pull request checks so a broken contract blocks the merge.
What do contract tests not tell you?
Contracts guard interfaces. They say nothing about whether the behavior behind the interface is the behavior you intended. A provider can satisfy every pact and still calculate the wrong price.
If a coding agent changes both sides of an API in one session, it can update the code and the contract together, so a green contract run proves less than it appears to. A human-owned list of scenarios, and a way to see which of them have a test, keeps the intent separate from the implementation. TestChimp keeps scenarios as Markdown in your repo, links Playwright tests to them, and shows the ones with no test. See spec-driven testing and test coverage metrics for how to track that.
Frequently asked questions
What is API contract testing?
It is testing that checks an API provider and its consumers agree on request and response formats, without running the services together. Contracts can come from consumer tests, as in Pact, or from an OpenAPI document.
What is consumer-driven contract testing?
The consumer writes tests that record the requests it makes and the responses it needs. Those become a contract that the provider replays in its own build, so only the parts of the API consumers use are tested.
What does can-i-deploy do?
It is a Pact Broker CLI command that tells you whether the version you are about to deploy is compatible with the versions of the services it integrates with, so a CI job can block an unsafe release.
Is contract testing the same as testing against an OpenAPI spec?
Not exactly. Testing a provider against its OpenAPI document checks conformance to the spec. Consumer-driven contract testing also checks that the provider meets what each consumer actually expects. Many teams use both.
Does contract testing replace end-to-end tests?
No. It replaces much of the integration checking that end-to-end tests do between services, but you still need a few end-to-end tests to prove that key user flows work.
Which tools support API contract testing?
Pact is a widely used consumer-driven tool with implementations in many languages. Schemathesis generates tests from OpenAPI and GraphQL schemas. Which fits depends on whether you have known consumers or a public spec.
Know which scenarios your API tests really cover
Keep scenarios in your repo, link tests to them and see the gaps. 14-day free trial, no credit card.