@case-contract-testing/case

Case Contract Testing Framework

_{Briefcase sticker created by Gohsantosadrive on Flaticon}

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

Case 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.

Case releases follow semantic versioning, with two additional restrictions:

1. Before 1.0.0, Case 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

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

1. Case 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. Case doesn't yet support merging of contracts. This means that your whole contract must be defined in one test file.
3. Case currently is only compatible with Jest. At a later date, the jest support will be extracted, and the peer-dependency removed.
4. Case currently doesn't support reporting your verification results to a broker.
5. Case currently only has rudimentary support for retrieving contracts from a broker.
6. 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

Case 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 Case (unless you want to or something).

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

Like Pact, Case requires a broker to operate. To maximise Pact compatibility, Case 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 Case to always be compatible with both of these brokers.

Feature differences from Pact

• Drive contracts from the client or the server. Case 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 Case 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