Contract testing for microservices checks that two services still agree on the messages they exchange, without deploying both of them. The consumer records what it sends and what it needs back. The provider replays that record against its real code. If both pass, the services fit. If one fails, you know before release which change broke the link.
This guide is for CTOs, founders and QA leads who run several services and keep hitting integration bugs late. It uses the Pact documentation as its source and ends with an order of work.
What contract testing is
The Pact documentation defines contract testing as checking each application in isolation, to confirm that the messages it sends or receives match a shared understanding. That shared understanding is written down as a contract.
The same page describes the usual alternative, integration tests that run services together, as expensive and brittle. Contract tests let you confirm that services work together without deploying everything first. The docs call this especially useful in setups with many services, where version conflicts between teams are common.
Pact is code first and consumer driven. The contract is generated when consumer tests run. Each contract is a set of concrete request and response examples.
The service that makes the request or reads a message. It defines what it needs.
The service that answers the request or writes the message. It must keep meeting what consumers need.
The record of interactions that the consumer tests produce. The provider uses it to verify itself.
The shared store for contracts and verification results. It lets teams check compatibility before release.
How a Pact test runs
How Pact works describes the flow in two halves.
On the consumer side, the test registers an expected request and response with a mock provider. The consumer code then sends a real request to that mock. The mock checks the request against what was expected and returns the agreed response. Finally the test confirms the consumer handles that response correctly. Each interaction is tested on its own.
When all interactions pass, Pact writes the pact file. On the provider side, Pact sends each recorded request to the real provider and compares the actual answer with the minimal expected one. Verification passes if the response contains at least the expected data. Where an interaction needs certain data to exist first, provider states set that up before the request is replayed.
- 1Consumer writes a testIt states the request it will send and the minimal response it needs.
- 2Pact file is generatedEvery passing interaction is recorded as a contract.
- 3Contract is sharedThe file is published so the provider team can reach it.
- 4Provider verifiesPact replays each request against the real provider code.
- 5Result is publishedThe pass or fail result is stored against the exact versions.
The word "minimal" matters. Because the contract holds only what consumers use, the provider is free to change anything no consumer relies on. That is the main reason teams find contract tests less brittle than full integration suites.
What contract tests do not cover
Contract tests are narrow on purpose. The Pact docs say they should focus on messages, meaning requests and responses, and not on behavior. They also warn that using contract tests as a replacement for functional tests leads to brittle suites.
Some limits to plan for:
- Examples, not a full specification. A Pact contract covers the concrete examples in the tests. It is not the same as a schema such as OpenAPI, which describes every possible state.
- Only current consumers count. Behavior that no consumer uses today is not tested. That is a feature for the provider, and a gap if you expect the contract to describe the whole API.
- Data-dependent checks are fragile. Pact tests work best when passing does not depend on the specific data the provider returns. Check the shape and type of fields, not live values.
- Queues are out of scope. For asynchronous systems, Pact checks the message payloads. It does not test the message queue itself, so other tests must cover that.
For message-based systems, the docs recommend keeping protocol-specific code, such as a Lambda handler, separate from the domain logic that processes the message. That way the logic can be tested directly.
Gate releases with can-i-deploy
Contracts only help if a failing one stops a release. That is the job of can-i-deploy. It checks whether a version is compatible with the versions of its integrated applications already in a target environment. It reads the Pact Matrix, the table of consumer and provider versions that have been verified against each other.
The answer is yes or no. Exit code 0 means yes and exit code 1 means no, so a CI step can fail the build. A dry run mode reports the result without failing the pipeline. That is a safe way to introduce the gate before you enforce it.
The check needs three things in place:
- Providers publish verification results to the Pact Broker.
- Environments such as production are defined in the Broker.
- Each deployment is recorded, so the Broker knows what runs where.
The recording guide explains the last point. For APIs and consumer apps deployed to known instances, you run pact-broker record-deployment at the end of a deployment, once it can no longer fail. For mobile apps and libraries published to a store or repository, you use pact-broker record-release instead. When a version is no longer supported, record-support-ended removes it from safe-to-deploy checks.
The docs also note that comparing against a specific environment gives the most accurate answer. Without one, the check compares against the latest version of each integrated application, which may not match what is live.
A sensible order of work
You do not need to cover every service on day one. Start where integration failures hurt most.
- Pick one pair. Choose a consumer and provider that break often, such as a mobile app and its backend API.
- Write consumer tests for the calls that matter. Keep each interaction minimal. Avoid depending on specific returned data where you can.
- Add provider verification to the provider's pipeline. Use provider states for any data an interaction needs.
- Publish to a Broker. Share contracts and results so both teams see the same record.
- Record deployments, then run can-i-deploy in dry run. Watch it for a few releases.
- Enforce the gate. Make a failing check block the release.
- Keep end-to-end tests small. Let them cover the few business flows that cross services.
Teams that already use QA and software testing practices can usually slot this into an existing CI pipeline. Mobile apps that depend on several backends are one place to start. If you are building those apps, see mobile app development. The way a QA gate sits in a release is also described on the how we work page.
Choosing who owns it
Contract testing fails more often from unclear ownership than from tooling. Consumers write the contracts, providers run the verification, and someone owns the Broker and the deploy gate. Without a named owner, contracts go stale and the gate gets switched off.
If you lack the people to set this up, a dedicated team or staff augmentation can supply QA and backend engineers who work inside your repos and pipeline.
Next step
Pick your most failure-prone service pair and write down the five calls between them that would hurt most if they broke. That list is your first set of contracts. If you want a second opinion on where to start, book a technical call through the contact page. It is a technical conversation, and an NDA can be signed first on request.
Frequently asked questions
What is contract testing in simple terms?
It checks each service on its own against a shared agreement about the requests and responses it sends and receives. You do not need to deploy every service together to find out whether they still fit.
Does contract testing replace end-to-end tests?
No. Pact's own documentation warns against using contract tests as functional tests, because that leads to brittle suites. Contracts cover the message shape. You still need tests for business behavior.
Who writes the contract in consumer-driven contract testing?
The consumer. Its tests record the requests it makes and the minimal response it needs. The provider then replays those requests to confirm it still meets them.
What does can-i-deploy do?
It asks the Pact Broker whether a version is compatible with the versions already in a target environment. It returns yes or no, and the exit code can fail a pipeline before a risky release goes out.
Need help with QA and testing?
Talk to the engineers who would do the work. We reply within one working day.

