# Contract Testing

Contract testing checks that communicating applications agree on the requests, responses, or messages they exchange across an interface.

- Type: practice
- Domain: Engineering & architecture
- Level: Intermediate
- Last reviewed: 2026-10-19
- Original: [Soroush’s Product Wiki](<https://wiki.soroush.uk/topic/contract-testing/>)

## What it means

Contract testing verifies an integration boundary against a shared description of expected communication. Consumer-driven contracts capture what a client actually needs and verify those expectations against the provider. Provider specification checks can also test documented behavior, but a schema alone does not prove that real consumers use the interface correctly.

## Why it matters

An API can remain syntactically valid while breaking a customer-facing client. Contract checks reveal incompatible changes earlier and reduce reliance on keeping every service running together for every test.

## When to use it

Use it for independently evolving services, APIs, and message consumers with meaningful compatibility risk. Keep the checked interactions connected to real consumer behavior. Retain broader tests for deployment wiring, authentication configuration, and complete business workflows.

## How it works

1. Identify consumers, providers, and the interactions whose compatibility matters.
2. Capture required requests, responses, or messages with realistic states.
3. Verify the consumer against its expectations and the provider against the contract.
4. Record contract versions and compatibility results for deployment decisions.
5. Review failures with both teams and retire contracts for unsupported consumers.

## A practical example

A mobile client requires a numeric price and a currency field. A provider change omits currency for discounted items. Contract verification against that provider state fails before release, allowing the teams to preserve compatibility without running the full mobile app in every backend test.

## Where it breaks

Coverage is limited to recorded expectations and provider states. Incorrect or stale contracts preserve false assumptions. These checks do not establish real network behavior, performance, or every business rule; naming and tooling also vary across teams.

## Common mistakes

- Testing only schema validity and claiming consumer compatibility.
- Creating contracts disconnected from actual client usage.
- Expecting contract checks to replace complete-workflow verification.

## Sources

1. [Introduction to Pact and contract testing](<https://docs.pact.io/>) — Pact Foundation · Official documentation
2. [Contract Test](<https://martinfowler.com/bliki/ContractTest.html>) — Martin Fowler · Practitioner guidance

## Related topics

- [Integration Testing](<https://wiki.soroush.uk/topic/integration-testing/>)
- [API Versioning](<https://wiki.soroush.uk/topic/api-versioning/>)
- [Microservices Architecture](<https://wiki.soroush.uk/topic/microservices-architecture/>)
