A couple of weeks ago, while at TestBash Manchester, I attended the “Contract Testing in Practice with Pact” workshop led by Pierre Vincent. I had some knowledge of the topic but the workshop helped me get some concepts straight, that either I was not familiar with or I had all wrong.
Here are some of the things I’ve learned. Hopefully I got them right.
The aim of contract tests should be to check if there are any changes in the structure of an API (renamed fields, change of type of data, etc.) and not its business logic.
As an API consumer
- You provide the contract, stating your expectations of what a call to an API should return.
- Contract tests serve as unit tests of the structure of your request.
- Contract tests should respect the tolerant reader pattern. As the post says, you should “only take the elements you need, ignore anything you don’t.”
- Running the contract tests you created doesn’t inform you of any changes from the provider’s side.
- If you are consuming external APIs contract testing won’t really work for you. Unless you have a way of ensuring that the external providers will execute the contracts you supply them with.
As an API provider
- Running contract tests lets you know if you still respect the way your consumers use your API.
- In case a contract test fails, you should either fix it or start discussions with the consumers about mutually changing the contract.
- As a provider of an external service you probably don’t want to have to execute and respect contract tests for each consumer of your API. But still, probably you don’t want to upset them every time you make a change. An idea would be to use the documentation of the latest version of your API as your consumer contract test, and make sure you respect that.
You still need to talk to people
- Before deciding on the tool you will use to implement contract tests, discuss what your API should look like. What are the requests that the consumer will send and what are the responses that the provider can return? Don’t forget to include the responses to error messages.
- In case there are conflicts between various consumers’ contracts, provider and consumers need to talk.
- In case the provider needs to do major changes to the API, provider and consumers need to talk.
In a nutshell, as far as I understand it, contract tests check structural compatibility and can be maintained in a meaningful way if consumer and provider have a way to talk and influence each other.
P.S. If you want to know more (and 100% accurate) information on contract testing with Pact, you can have a look at Pierre’s TechBeacon article on the topic. Still trying to get through all the excellent references in it myself.