Consumer-driven contract testing is an approach to API testing in which the consumer of an interface specifies what data it sends and which responses it expects. These tests produce a machine-readable contract that both sides test against independently. If a test fails, the software doesn’t build.
Key Takeaways
- Consumer-driven contract testing solves a structural problem: the consumer, not the provider, defines which data and formats it expects from an interface.
- The repository-based approach with OpenAPI and Renovate only checks the syntax and structure of an interface. It misses semantic changes such as a single enum value being removed.
- Pact turns consumer tests into a machine-readable contract that both sides can test against independently, without needing the other side to be live.
- A failing contract test blocks the build. As long as the contract is broken, the software cannot be released.
Three Ways to Protect an API Against Changes
If you provide or consume a REST interface, you have roughly three options for keeping changes under control. The simplest is just talking: two teams sit down, agree on the interface contract verbally and are done quickly. From a tester’s point of view, that is rarely enough, and this is where repository-based versioning and consumer-driven contract testing come in.
The other two options are backed by tooling and can be automated. The first is repository-based and versions the interface description itself. The second is contract testing, where the consumer spells out its expectations of the interface and makes them testable.
Both approaches work best on top of OpenAPI. You describe the interface in OpenAPI first and generate the code from that description. That saves programming effort and is less error-prone than writing the interface by hand.
How the Repository-Based Approach with OpenAPI and Renovate Works
In the repository-based approach, the OpenAPI description is treated as a separate, versioned artifact. In a Java environment, the generated interface ends up in a Maven repository that holds nothing but this interface description.
The second component is Renovate. The tool reads the Maven POM file and checks the dependencies listed in it, not only those of the software but also those of the plugins. When Renovate finds a new version, it can automatically open a merge request in the connected repository.
If the build for that merge request passes, Renovate can merge it automatically as well. If the build fails, the merge request waits for a manual review. Someone then checks whether there is a breaking change and what needs to be adjusted.
The benefit is that an interface change no longer slips through unnoticed. The consumer gets a new version, has to adopt it and runs into whatever has changed. This works even if nobody knows who uses the interface, because the producer simply publishes the change.
Why the Repository Approach Only Checks Structure and Syntax
Renovate detects changes to structure and syntax, but not semantic shifts. That is the main limitation of the approach.
An example makes it clear. A parameter is defined as a string, but the consumer actually processes only two valid values, a kind of enum. If the producer drops one of those values, the syntax doesn’t change: it is still a string. The repository-based comparison therefore doesn’t catch it.
A principle from interface design applies here. What an interface sends out should be described as strictly as possible. What comes in should be accepted liberally, letting through as much as possible. As long as it is about syntax, this is easy to describe. As soon as semantics come into play, you need a different kind of test.
Consumer-Driven Contract Testing: The Consumer Defines What It Expects
In consumer-driven contract testing, whoever wants to use the interface describes what they expect from it. They define what they send and what they must get back. That makes semantics testable too.
Andrej Thiele uses the Pact tool and its builder pattern for this. Through a DSL, the consumer describes in detail that, for example, it sends a GET request with certain data and receives data in a defined format with certain variations. For every variation it cares about, it writes a separate case.
This solves the enum problem of the repository approach. If the consumer expects exactly two values, it lists both as examples. If those values suddenly disappear, the test fails immediately. The consumer only tests what it actually evaluates. If it cares about three out of many fields, it writes tests for those three only. The rest doesn’t matter to it.
How the Workflow Between Consumer and Producer Runs
The process starts on the consumer side, where the test is written first. From that test and its data, a contract is created: a document stored either in the file system or on a Pact Broker.
The Pact Broker can be secured via HTTPS so that only parties who know the interface and intend to honor the contract can access it. Consumer and producer both read the same contract.
From the contract, the framework generates a kind of mock server. On the consumer side, the software fires its request straight at it. On the producer side, exactly the data the consumer specified is sent from the contract to the producer, so the producer is checked against real expected values as well.
This decouples the teams. The consumer doesn’t have to wait for the other system to be finished and can work against the contract right away. Several consumers can write their own tests independently, and those tests don’t need to overlap.
Contract Testing Doesn’t Work Without Talking
Contract testing doesn’t replace coordination between teams. It just makes it necessary less often. It is usually configured so that the software can’t be released at all if one of the contract tests fails.
That is exactly what forces a conversation when in doubt. If one team changes something and another doesn’t follow, the affected team sees that something is failing but doesn’t necessarily know what happened. Then they have to talk to the other team.
“Even as a computer scientist, you have to talk an awful lot.”
(Andrej Thiele)
The hard advantage of this mechanism: nobody can dodge the check. If the test doesn’t pass, the software doesn’t build.
Contract Testing vs. the Repository Approach: When Each Pays Off
Contract tests come from the microservice world. There, interfaces are deliberately kept small, so you don’t end up with masses of tests. With more complex interfaces and five or six different consumers each writing their own tests, the test base can grow considerably.
The comparison below sums up the differences:
| Criterion | Repository-Based (OpenAPI + Renovate) | Consumer-Driven Contract Testing (Pact) |
|---|---|---|
| Checks | Structure and syntax | Syntax and semantics |
| Control | Producer-driven | Consumer sets expectations |
| Detects changed enum values | No | Yes |
| Knowledge of consumers | Not needed | Known, coordinated consumers |
| Getting started | More effort | Easier |
| Ongoing operation | Easier | More effort |
A mix is possible. You might start with the Renovate approach and add contract tests where semantics start to matter. The rollout is iterative: not every consumer has to join from day one, and the setup grows step by step.
What You Need for a Setup
The effort depends on the technical know-how you already have. For a demo setup, the whole chain can be rebuilt locally in a Docker environment, with your own GitLab, Nexus Community Edition and a Renovate server. Renovate can also run as a GitLab runner.
Pact tests are the easier way to get started. You don’t necessarily need a Pact Broker: contracts can also be exchanged via the file system or a shared directory both sides can access. In day-to-day operation, on the other hand, the Renovate variant is much easier to handle.
Integration and reporting stay within familiar territory. Pact tests are written as ordinary JUnit tests and run as integration tests. The output comes from the JUnit framework and can be reused in the pipeline. The Pact Broker also shows when contracts have been broken. At its core, though, you see the result directly in the software: it doesn’t build when the check fails.


