Contract Testing

In Turkish: Sözleşme Testi

Updated September 30, 20262 min read

In short

Contract testing is a technique that checks whether two services agree on the requests and responses they exchange, without running both of them together.

What is contract testing?

Contract testing verifies that two pieces of software that talk to each other, usually an API consumer and an API provider, agree on how they communicate. The agreement, called a contract, describes the requests the consumer sends and the responses it expects, including fields, data types, and status codes. Each side is tested against the contract separately, so neither needs the other to be running.

In the common consumer-driven approach, the consumer's tests run against a mock provider and record every interaction they rely on in a contract file. That contract is shared with the provider team, often through a central store called a broker, and the provider's test suite replays each recorded request against the real provider and checks that the responses match. If a provider change would break a consumer, the provider's build fails before the change is deployed.

Think of a power plug and a wall socket: as long as both follow the same standard, they fit together, and you can check each one against the standard without plugging them in. Contract testing is most useful in microservices architectures and for widely used APIs, where many teams deploy independently and running every service together for end-to-end tests is slow and fragile.

Contract testing is often confused with integration testing and with schema validation. An integration test runs real components together, while a contract test checks each side in isolation against a shared agreement, which makes it faster and clearer about which side broke compatibility. Validating responses against an OpenAPI schema is related, but consumer-driven contracts capture only the parts of the API that consumers actually use, so providers know which fields are safe to change.

Key takeaways

A contract describes the requests a consumer sends and the responses it expects.
The consumer and the provider are each tested against the contract separately.
In consumer-driven contract testing, consumers define the contract and providers verify it.
Contract tests catch breaking API changes before deployment, without a full end-to-end environment.
They complement unit and integration tests rather than replacing them.

Example

A simplified consumer-driven contractyaml

# Recorded by the consumer's tests, replayed and verified by the provider's tests
consumer: web-app
provider: users-api
interactions:
  - description: fetch an existing user
    request:
      method: GET
      path: /users/42
    response:
      status: 200
      body:
        id: 42              # the consumer relies only on these two fields,
        name: Ada Lovelace  # so the provider is free to change the others

Readers ask

What is the difference between contract testing and integration testing?

An integration test runs real components together to see whether they work as a whole. A contract test checks each side separately against a shared agreement, so it is faster, needs no shared environment, and shows exactly which side broke compatibility.

What is consumer-driven contract testing?

It is a style of contract testing in which the consumers of an API write down the interactions they depend on, and the provider runs those contracts as tests. This lets the provider change anything its consumers don't use without fear of breaking them.

Does contract testing replace end-to-end tests?

Not entirely. Contract tests greatly reduce how many end-to-end tests you need to check compatibility between services, but a few end-to-end tests are still useful to confirm that critical user journeys work in a fully deployed system.