Stop app releases breaking your API with contract testing
Short answer: If your mobile app, website front end and backend API are built separately and keep breaking each other after releases, consumer-driven contract testing helps. With a tool like Pact, the app's tests record exactly which requests it makes and which response fields it relies on. That record, the contract, is then checked against the real API in the API's own test pipeline. If a backend change would break a field the app depends on, the API build fails before anything ships.
The problem it solves
Many small businesses have at least two pieces of software that talk over an API: an iPhone and Android app talking to a backend, a website front end calling a separate service, or an internal tool reading from a partner's system. Each side has its own tests, and each side's tests pass. Then a backend developer renames a field, changes a date format or makes a value optional, and the app crashes for customers.
The usual answer is end-to-end tests that run the whole system together. They catch some of this, but they're slow, need every service running, and often fail for reasons unrelated to the change being tested. Pact's own documentation argues that contract tests, used alongside or instead of traditional end-to-end integration tests, are cheaper in the long run, partly because they give developers very fast feedback.
The vocabulary
Pact's documentation frames a contract as an agreement between a consumer, such as a client that wants to receive some data, and a provider, such as an API on a server that supplies it. The consumer is whoever calls; the provider is whoever answers. One service can be both, consuming one API while providing another.
How consumer-driven contracts work
- The consumer writes tests against a mock. In the app's test suite, a developer describes an interaction: "when I request order 42, I expect a 200 response with an
id, astatusand atotal." Pact runs a mock provider that answers exactly that, and the app's code is tested against it. - Pact records the contract. Every interaction the consumer tests is saved to a contract file listing the requests and the parts of each response the consumer actually uses.
- The contract is shared. It's published to a central place, commonly a Pact Broker, so the provider team can fetch it.
- The provider verifies it. In the API's pipeline, Pact replays each request against the real API and checks the responses match what consumers expect.
- Both sides know whether they can deploy. If verification fails, the provider knows exactly which consumer and which field would break.
The important idea is that only fields the consumer really uses are in the contract. The provider can add new fields freely and change anything nobody relies on, without fear.
What to put in a contract
Keep contracts focused on what the consumer needs:
- Shape over exact values. Use matchers, such as "any string" or "an integer", rather than fixed data, so contracts don't fail because test data changed.
- The key scenarios. Successful responses, not-found responses and validation errors your app handles differently.
- Provider states. A consumer can say "given an order exists" and the provider's verification sets that up in its test data.
Leave out exhaustive business-rule checks. Contract tests confirm the two sides can talk; the provider's own tests confirm the business logic is right.
Fitting it into your pipelines
- Consumer pipeline: run the contract tests with unit tests, then publish the contract with the app's version number.
- Provider pipeline: fetch contracts for the consumer versions currently in production and in testing, verify them, and publish the results.
- Before deploying either side: check whether the versions you're about to deploy have compatible, verified contracts. The broker's tooling can answer that question automatically.
Mobile apps make this especially valuable. Old app versions stay on customers' phones for months, so the backend must keep honouring the contracts of every version still in use.
When contract testing is worth it
It earns its keep when:
- Different people or teams own the client and the server.
- You release the client and server on different schedules, including app store releases.
- Several consumers use the same API.
- End-to-end tests are slow or flaky and you want them to cover less.
It's less useful for a single-developer project where the front end and back end are always deployed together, or for third-party APIs you don't control, where you can't run verification on the provider side.
Common pitfalls
- Contracts copied from API documentation. A contract should come from the consumer's real code and tests, or it checks what someone hoped the app uses rather than what it does.
- Over-specified responses. Asserting every field and exact values turns contracts into brittle snapshots that fail for harmless changes.
- Verifying only the latest consumer. Old app versions in customers' hands still need their contracts honoured.
- Nobody owning failures. Agree up front who looks at a failed verification and how quickly.
A worked example
Consider a hypothetical Limerick gym chain with a booking app built by an agency and a backend maintained in-house. Twice, a backend release changed the class schedule response and the app showed empty timetables until a hotfix. The teams added Pact: the agency's app tests generated contracts for schedule, booking and membership endpoints, published them to a broker, and the in-house API pipeline verified them on every build. The next time a developer tried to rename a schedule field, the API build failed with a message naming the app version that used it.
FAQ
Is Pact only for microservices?
No. It works for any client and server that talk over HTTP or messages, including a single mobile app and its backend.
Do I still need end-to-end tests?
A few, for critical journeys like checkout. Contract tests let you keep that set small.
What languages does Pact support?
Pact has implementations for many common languages. Check the documentation for yours.
Who writes the contract tests?
The consumer team writes them, which is why it's called consumer-driven. The provider team runs the verification.
If your app and API keep breaking each other after releases, describe how they're built and released and we'll suggest a testing setup.