ContractCase Contract Testing Framework

Briefcase sticker created by Gohsantosadrive on Flaticon

Read the documentation here. Documentation is currently in-progress. Feedback welcome!

ContractCase is a next-generation consumer-driven contract testing framework, building on many of the lessons from maintaining the excellent Pact contract testing framework. It is our belief that contract testing is the best way to get deployment confidence for your applications and services.

ContractCase releases follow semantic versioning, with two additional restrictions:

1. Before 1.0.0, ContractContractCase is in Beta, and the API is considered unstable. Breaking changes will be indicated in minor version bumps- that is, 0.2.0 and 0.3.0 are not entirely compatible.
2. Patch versions will always be backwards compatible.

Breaking changes will always be detailed in the changelog.

Incomplete documentation is here. By way of apology for the unstable API, at least one new page of documentation will be added every time a breaking change is released during the beta period.

Caveats and limitations

WARNING: THE API IS UNSTABLE AND MAY CHANGE BETWEEN MINOR VERSIONS

ContractCase is now available and should work for both client and server driven http/https contracts. Feedback on the ContractCase API / DSL and (especially) naming conventions very welcome. However, the following caveats should be kept in mind:

1. ContractCase is currently only available in Javascript / Typescript. At a later date, support for Python, Java, C# and Go will be added, using JSii. There are no plans to add other languages at this time.
2. ContractCase doesn't yet support merging of contracts. This means that your whole contract must be defined in one test file.
3. ContractCase currently is only compatible with Jest. At a later date, the jest support will be extracted, and the peer-dependency removed.
4. ContractCase currently only has rudimentary broker support - it works but it's not very configurable.

Although the test coverage is high, and great care has been taken to ensure that the results are correct, there may still be bugs. Please open an issue if you experience any problems.

If you want to get started immediately, we recommend starting with either the client-driven end-to-end test, or the server-driven end-to-end test. Make sure you remove printResults: false.

You can follow the detailed progress by reading the maintainer todo list. These caveats will be updated as progress is made.

I'm fine with all the caveats, how do I get started?

npm install --save-dev @case-contract-testing/case

You may also need the peer dependencies:

npm install --save-dev jest@^29.4.3

For Pact users

TODO: Pull this section out and expand into detailed documentation

ContractCase is intended to solve some of the pain points when using Pact - if you are not hitting those pain points, there is no need to switch to using ContractCase (unless you want to or something).

ContractCase has a very similar philosophy to Pact. You write your pacts as a contract, which is a series of examples.

Like Pact, ContractCase requires a broker to operate. To maximise Pact compatibility, ContractCase works with the Pact broker. We recommend either:

• The Pact Broker for users wanting to host their own broke
• The excellent Pactflow Broker for those needing SaaS and enterprise features

We plan for ContractCase to always be compatible with both of these brokers.

Feature differences from Pact

• Drive contracts from the client or the server. ContractCase is always consumer-driven, but what you are consuming might be a request, instead of a response.
  • Example client-driven end-to-end test
  • Example server-driven end-to-end test
• Contract verification is an individual test in your test suite per interaction, rather than one test for all interactions. This provides much more granular feedback
• All matchers are valid in all contexts
• Currently it only supports Javascript / Typescript, with Jest

Planned differences

• Native message formats - actually invoke SQS queues / kafka messages etc during verification
• Easy user extensions - write extensions for ContractCase just by extending a class in JS, Python, Go or Java

Roadmap

1. Pact Parity (in progress, close to complete)
2. "Provider" driven contracts (done)
3. Documentation (in progress)
4. RELEASE BETA (done)
5. Support Python, C# and Go
6. Arbitrary combinations of request/response pairs, incidentally including native SQS support
7. Pass-through APIs
8. Plugins and arbitrary extensions

For the gory details, you can see the implementation notebook / todo list here