Contract Testing for Microservices

Contract testing approaches compared: consumer-driven, schema-driven and bi-directional contracts feeding into one verified check
Nov 12, 2026
12 mins
read
Atulpriya Sharma
Sr. Developer Advocate
Improving
Read more from
Atulpriya Sharma

Table of Contents

Start your free trial.

Nov 12, 2026
12 mins
read
Atulpriya Sharma
Sr. Developer Advocate
Improving
Read more from
Atulpriya Sharma
Atulpriya Sharma
Sr. Developer Advocate
Improving
What contract testing is, how consumer-driven, schema-driven and bi-directional contracts compare, when to skip it, and how a platform team rolls it out.

Table of Contents

Executive Summary

The payments team renames one field in an API response, from status to state. Their own tests pass and staging is green. After the release, a service owned by the orders team starts failing in production because it still looks for the status field.

The owners of the API had no list of who depended on that field, and the owners of the dependent service never heard it was changing. Both teams tested their own code properly, and the gap between the two services went untested.

In microservices, contract testing closes that gap by writing down what two services expect from each other and checking both sides against it.

This is part 1 of our contract testing series. We start with what contract testing is, then look at the three main approaches and when to use contract testing or skip it. We finish with how a platform team can roll it out across teams.

What Is Contract Testing?

In our earlier example, the orders team's service is the consumer, the service that makes a request, and the payments team's service is the provider, the service that answers it. A contract is the written agreement between them about what the request looks like and what the response contains.

Pact, an open-source tool for testing HTTP and message integrations with contract tests, defines contract testing as checking each application in isolation against that shared, documented understanding. Each side is tested against the contract separately, so you can confirm that two services will work together without deploying everything first.

It starts with someone writing down what the consumer expects. The contract is then shared where the provider can find it, a check runs against it on every change, and the results appear in one place. If anything doesn't match, the check fails and blocks the deployment.

Why integration tests and shared staging fall short

The usual alternative to contract testing is an integration or end-to-end test in a shared staging environment. Pact's docs describe these as expensive and brittle. Our integration vs E2E guide lists race conditions, timing dependencies, shared state and environment drift as the usual causes of flaky failures, and notes that cryptic failure messages make root causes hard to find. Rerunning often means resetting the cluster to a known state, which can be time-consuming and error-prone.

Mocks are faster, and they bring their own risks. A mock written months ago can keep answering the old way while the real service has moved on, so the consumer's tests stay green.

Where it sits between unit and end-to-end tests

Contract tests replace one class of integration test: the ones that check how one service uses another's API. Unit tests still cover each service's own logic, and a small set of end-to-end tests still covers user journeys. Our microservices testing guide covers the full testing strategy.

What contract testing doesn't catch

A contract test checks the shape of requests and responses, not what the provider does with them. Business logic stays with the provider's own tests, and contract tests are a poor fit for performance and load testing. A contract test can still pass when the provider's core logic is wrong.

When to Use Contract Testing (and When to Skip It)

Contract testing suits some integrations better than others. Some teams get a lot out of it, while others add effort for very little return. The difference usually comes down to who owns the two services and how many teams are involved.

Where it pays off

Contract testing earns its cost when you own both sides of an integration and both are still changing. The consumer team and the provider team agree on a contract and check each other on every release, so neither has to wait on a shared environment to find out whether a change is safe.

It matters most when many teams release on their own schedules. A provider that ships a schema change before its consumer has updated takes that consumer down, and in some integrations the failure reaches customers.

Where to skip it

Skip it when the other side of the contract is out of reach or has nothing to check:

  • The other team won't take part. A contract that only one side checks protects nobody.
  • Public APIs. You cannot identify every consumer or keep a relationship with each one.
  • Pass-through APIs. They forward requests downstream without validating them. Any request gets the same response, so there is nothing to check.
  • Standard protocols such as OAuth2. Pact's own FAQ recommends against using it here, because standards are well defined and rarely change, and simpler testing options exist.

Contract Testing Approaches

Once you decide contract testing fits, the next decision is where the contract comes from. Three approaches cover most cases, and each answers that question differently: the consumer writes it, the provider writes it, or both do.

Consumer-driven contracts

The consumer team writes the contract from its own tests. It records which requests it sends and which parts of the response it reads, and the provider checks that it can still serve exactly that. In our example, the orders team records that it calls the payments API and reads the status field. When the payments team renames the field to state, the check fails in the payments pipeline before the release.

The contract shows what consumers actually use, which makes it precise. The cost is that every consumer team has to write and share its tests.

Schema-driven contracts

The provider team writes the contract as an API description, usually an OpenAPI file, and checks run against the real service to confirm it matches. The payments team publishes a description with a status field, and if the service starts returning state, the check fails. Consumers do nothing, so this is the quickest to start when descriptions already exist.

The same description can also generate mocks for consumers to test against. Prism does this for HTTP APIs, and Microcks does it for OpenAPI and AsyncAPI descriptions.

The limit is that a description covers everything the provider could return and says nothing about which fields consumers rely on. The check also passes if the payments team renames the field in the description too, because the service still matches what it describes. Catching that takes a separate check that compares the old and new descriptions, such as oasdiff, which reports breaking changes like a removed required response property.

Bi-directional contracts

Both sides publish, and a tool compares what they published. The consumer's contract comes from its existing tests or mocks. The provider publishes its API description along with the results of its own tests against the running service.

In our example, the orders mock expects status and the payments description now says state, so the comparison fails before either service deploys. This is a feature of the commercial PactFlow product, and the open source Pact Broker does not offer it.

Which approach to pick

Pick one approach for the whole organization. Without one agreed approach, the gaps show up quickly.

Say the payments team runs consumer-driven checks and expects a contract from every consumer, while the orders team follows a provider-driven approach and sees no reason to write one. Payments waits for a contract that never arrives, orders assumes the provider is checking what it needs, and the rename from our opening example slips through. Agree on the approach, and if possible the technology, before starting.

Choose consumer-driven for critical integrations between different teams. Choose schema-driven when you already keep API descriptions and want to start quickly. Choose bi-directional to retrofit onto existing systems, which is where its vendor recommends it.

ParameterConsumer-drivenSchema-drivenBi-directional
Who writes the contractEach consumer team, from its own testsThe provider team, as an API descriptionConsumers from tests or mocks, the provider as an API description
What a pass provesThe provider can serve what each consumer usesThe running provider matches its descriptionThe consumer's needs fit the description, and the provider matches it
Cost to adoptEvery consumer team writes and shares testsLow when descriptions already existReuses existing mocks, but needs a commercial product such as PactFlow
Blind spotConsumers nobody knows aboutWhich fields consumers rely onOnly as strong as the provider's own tests
When to use itCritical integrations between different teamsOrganizations that already keep API descriptionsRetrofitting onto systems that already have mocks

How to Run Contract Testing in Kubernetes

Choosing an approach settles who writes the contract. Where the contract lives and where the checks run are separate questions, and Kubernetes gives both a natural answer.

Where the contract lives

An API description belongs in Git next to the service, versioned with the code, so a change to the API and a change to its description arrive in the same pull request. Consumer-driven contracts come out of consumer tests and get published to a shared place, usually a broker, where the provider's pipeline can fetch them.

Where the checks run

A provider check needs the provider running with its dependencies and test data, and in a cluster those already live in a namespace. Running the check as a workload in the same cluster keeps it close to them. Testkube runs tests this way, as Kubernetes workloads in your clusters, using any tool packaged as a container image.

Ephemeral environments also remove the wait for a shared staging environment. For small setups a CI runner is enough, and the move to the cluster makes sense once providers need their dependencies running next to them.

What blocks a deploy

With an API description check, the rule is simple. If the check fails, the pipeline step fails and the release stops, which makes the check a quality gate.

Consumer-driven contracts need one more piece. Each check verifies one version of a consumer against one version of a provider, so something has to remember which pairs have passed. A central service keeps that record. Before a deploy, the pipeline asks it one question: has this version been verified against the versions running in production? If the answer is no, the release stops.

Testkube can start these checks automatically, either when a deployment's image changes or after each sync in a GitOps flow. Both run after the change is already in the cluster, so they verify what has just deployed. To stop a change before deployment, Testkube's GitHub integration can run the checks on each pull request and block the merge when they fail.

Who Owns Contract Testing on a Platform Team

A shared setup only works when everyone knows who maintains what. Contract testing sits between teams, which makes ownership more important than it is for most tests, and it is easy for the platform team to end up owning too much.

Platform team and service team responsibilities

The platform team owns the shared setup, and each service team owns what is specific to its own service:

Platform teamService teams
The shared setup that runs the checksThe contracts for their own services
How the deploy rule is enforcedThe test data behind each contract
Visibility of results across teamsFixing a failure when a check goes red

Keeping that line clear matters because a platform team that ends up writing every test becomes the bottleneck, a pitfall we describe in our post on test unification.

Tools do not replace conversation between teams. Idealo found the same thing when it rolled out consumer-driven contract testing across many teams and services. Its published lessons, written after about a year of use, say tools only help teams talk to each other more efficiently.

How to Roll Out Contract Testing Across Teams

With ownership settled, the next question is how to start. Rolling out contract testing to every team at once invites resistance, so it works better in stages that each deliver something on their own.

The three levels of a contract testing rollout

  • Level 1. Pick one high-risk integration, such as the payments and orders pair from our example, and add a check to an existing CI job. The two teams involved learn the approach on a problem they already feel.
  • Level 2. Build a shared setup that every service can use, and put a deploy rule on the critical integrations. This is where the platform team starts to carry the load.
  • Level 3. Set organization-wide standards, give teams visibility into each other's results, and let new teams onboard themselves.

If you track progress against a broader scale, our testing maturity model advises the same approach: start simple and add complexity gradually.

What slows adoption

Agreeing on the approach comes first, and it takes longer than teams expect, because the tooling is shared and changing it later affects every team. The learning curve and the adoption cost come next.

The cost adds up: each consumer team has to learn the tool, and someone has to run the shared store for contracts and extend provider pipelines.

When Contract Testing Makes Sense for Your Platform

Contract testing earns its place when many teams release independently and a platform team is willing to own the shared setup that runs the checks. In that setup, the field rename from our opening example is caught before it reaches production. A check fails before the release, and the orders team hears about it before its customers do. Where the other side will not take part, or the API is public or follows a standard protocol, a simpler check does the job.

Start with one integration, agree on one approach, and let the results make the case for the next team. Part 2 of this series shows how to run schema-driven checks for REST calls and Kafka events in Kubernetes, with Prism, Microcks and Testkube. It uses the schema-driven approach, so Pact is not part of it.

Want to see how Testkube runs tests like these inside your cluster? Start with the Test Workflows documentation, or talk to the Testkube team about your setup.

Frequently Asked Questions

What is contract testing in microservices?

Contract testing checks two services against a written agreement about what a request looks like and what the response contains. The consumer and the provider are each tested against that contract separately, so you can confirm they will work together without deploying everything first.

What is the difference between consumer-driven and schema-driven contract testing?

In consumer-driven contract testing, each consumer team writes the contract from its own tests, and the provider checks that it can still serve what each consumer uses. In schema-driven contract testing, the provider writes the contract as an API description, usually an OpenAPI file, and checks confirm the running service matches it.

Does contract testing replace end-to-end tests?

No. Contract tests replace the integration tests that check how one service uses another's API. Unit tests still cover each service's own logic, and a small set of end-to-end tests still covers user journeys.

When should you skip contract testing?

Skip it when the team on the other side will not take part, for public APIs where you cannot identify every consumer, for pass-through APIs that do not validate requests, and for standard protocols such as OAuth2.

How does a contract test block a deployment?

For an API description check, a failed check fails the pipeline step and the release stops. For consumer-driven contracts, a central service records which consumer and provider versions have passed, and the pipeline asks it before each deploy whether this version has been verified against the versions running in production.

Who owns contract testing on a platform team?

The platform team owns the shared setup that runs the checks, how the deploy rule is enforced, and visibility of results across teams. Service teams own the contracts for their own services, the test data behind them, and fixing a failure when a check goes red.

{{banner-get-started}}

Atulpriya Sharma
Sr. Developer Advocate
Improving
Read more from
Atulpriya Sharma

About Testkube

Testkube is the open testing platform for AI-driven engineering teams. It runs tests directly in your Kubernetes clusters, works with any CI/CD system, and supports every testing tool your team uses. By removing CI/CD bottlenecks, Testkube helps teams ship faster with confidence.
Get Started with a trial to see Testkube in action.