What is consumer driven contract testing?

Consumer driven contract testing is a type of contract testing that ensures that a provider is compatible with the expectations that the consumer has of it. For an HTTP API (and other synchronous protocols), this would involve checking that the provider accepts the expected requests, and that it returns the expected responses. For a system that uses message queues, this would involve checking that the provider generates the expected message.

Consumer driven contract testing may be achieved in a couple of ways -  by using an explicit contract, or by using a test harness that enforces an implicit contract.

Explicit contracts

When using an explicit contract, the consumer's expectations are serialised to a contract file during the execution of its own automated tests, and then "verified" against a provider during the provider's automated tests. The contract should be generated in a way that ties the contents to the consumer code, either by use of a test double that records requests/expected responses and writes them to a contract, or by generating expectations from class or schema files in the consumer codebase.

For synchronous protocols such as HTTP, a contract would typically contain a collection of request/response pairs. To verify the contract, each request would be sent to the provider, and the response compared to the expected one. If the actual responses match the expected responses, then the contract has been successfully verified. Any mismatches highlight an incompatibility between the consumer and provider.

Use of an explicit contract is best when the provider is able to incorporate the contract verification step into its own build, providing fast feedback to ensure that no breaking changes are made. This is ideal as it means that breaking changes should not be able to make it into a production release of the application or library.

Pact is a consumer driven contract testing tool that generates explicit contracts by using a test double that record requests and expected responses to a contract that is called a "pact".

Implicit contracts

When explicit contracts cannot be used, a similar outcome can be achieved by using a provider test double when running consumer tests, and executing a test harness at regular intervals to ensure that the real provider and the doubled provider behave the same way. The test harness enforces an implicit contract with the provider.

Use of a test harness to enforce an implicit contract is best when the contract verification process cannot be done during the provider's build - for example, for a public API or an OSS code library. While it won't stop breaking changes being released, it will ensure that they are highlighted as soon as possible.

arrow-up icon