Skip to main content

ContractCase Contract Testing Suite

ContractCase is a next-generation consumer-driven contract testing framework, building on many of the lessons from maintaining the excellent Pact contract testing framework.

Briefcase image

Briefcase sticker created by Gohsantosadrive on Flaticon

What is contract testing?​

Contract testing builds deployment confidence by testing whether two services (eg an http client and an http server) are able to communicate and understand each other.

If you've ever experienced downtime because of breaking API behaviours, then contract testing is for you.

  • You can think of it as a unit test, where the "unit" is the communication code of the consumer and provider
  • Or, you can think of it as integration tests that can run independently without the full stack
  • Or you can think of it as a mock service, where your requests can be replayed later against the thing that you mocked

In our view, contract testing gives much faster and more actionable feedback than any of the other approaches.

By using real examples, contract testing is more than just a type checker - it asserts that your providing service really does generate the responses you need in the conditions you need it to. It is an ideal companion to generated APIs using Swagger, gRPC or GraphQL, and very useful in microservice environments.

How does ContractCase work?​

ContractCase has two main modes of running tests:

  • Contract Definition - in contract definition you define a number of specific examples (say, HTTP request/response pairs) that the provider will return in various states (for example, a "getUser" request might return different responses depending on whether or not the user exists). state. Using these examples, you test one side of the communication boundary (say, the HTTP client).
  • Contract Verification - During contract verification, you take a list of examples (the contract file) written by a service that your service communicates with, and you confirm that it meets the expectations laid out in the contract.

Together, these form two halves of the same test. For example, with an HTTP client defining the contract, in contract definition you confirm that the client can generate a specific request, and understand a particular response. In contract verification you would then confirm that the server can understand the request, and generate a particular response.

Caveats and limitations​

ContractCase is currently in beta. Feedback is extremely welcome and encouraged - please help us get to a stable release by trying out the framework, and report any issues you experience.

During the beta, there are some caveats

  1. ContractCase doesn't yet support merging of contracts. This means that your whole contract must be defined in one test file.
  2. ContractCase currently only has rudimentary support for the contract broker. It works, but it's not very configurable yet - if you have a use case that isn't yet supported and you'd like it prioritised, please open an issue.
  3. ContractCase is currently only available in JS/TS and Java. At a later date, support for Python, C# and Go will be added.

Incomplete documentation is in the sidebar on your left (or at the bottom on mobile). By way of apology for any breaking changes during the beta, at least one new page of documentation will be added every time a breaking change is released during the beta period.