We already briefly mentioned the Pact Broker in the previous article (Using Pact for Consumer-Driven Contract Testing) and this piece will explain its usage and how it helps us run Pact and contract testing on CI pipelines.
The Pact Broker is an application that you can run in an EC2 machine (or other, depending on your cloud infrastructure). The Pact Broker is who manages the contract versions and providers, verification results, deployed versions, and releases.
These are the main features of the Pact Broker:
- Share and collaborate on contracts across teams
- Manage contracts across code branches and environments
- Orchestrate builds to know when it is safe to deploy
- Integrate into your processes and tooling
The Pact Broker has a UI where you can see the contracts, the verification results, etc. You can use it, but most of the access to it will happen by API by the CI.
List of pacticipants in Pact Broker. Source
And you can also see the contracts.
Example of a contract definition between two services on Pact Broker. Source
While seeing the relationship between services and the contracts is really nice, the real power of the Pact Broker lies in the integration with CI, mainly in managing contracts between the code branches and environments.
Pact Contract tests on CI
To better understand the whole flow in the CI, let’s see some images of how it happens.
Feature branches
Let’s start with the feature branch when a developer is still developing the new feature and it is not yet merged to master. As we already discussed, Pact is a consumer-driven framework, so the natural step is to create the first test on the consumer side.
So, the developer develops (😎) the Contract Tests, which generate the contract file and then verifies its own service.
CI pipeline of a feature branch for a Pact Consumer
Here no interaction with the Pact Broker is needed, as we are not publishing the contacts in feature branches. After all the tests pass and the normal Merge/ Push Request review process that we have today has been finished, the MR/PR can be merged to master. We are going to see what happens after merging later on.
For the provider, the flow is a bit different, and it requires that we already have a contract published to the Pact Broker as we need to get the contract to be verified.
CI pipeline of a feature branch for a Pact Provider
The provider fetches the latest contract from the Pact Broker and verifies it. Here the result is not published to the Pact Broker, it will break the provider pipeline if it is not complying with the contract defined by the consumer. Again, after all the tests pass and the MR/PR review finishes, it can be merged to master.
After merging to master
So, after you hit that so-expected “Merge” button, a few things will happen. When your service is the consumer, it will trigger your entire flow + the provider flow. When you are a provider, your CI flow is a bit shorter, as you only do your things.
Let’s see first the Consumer merge flow.
CI pipeline of merging to master for a Pact Consumer
As you can see above, we start by running the consumer tests that generate the contract, just like in the feature branch. The additional step here is to publish the contract to the Pact Broker, so the providers can use it to verify. Simply, this is the only addition to the feature CI flow for the consumer.
If the contract is new or has changed, the Pact Broker can trigger a webhook for the Provider CI. This step allows the provider to check the changes and see if it’s still compatible with the consumer. This webhook you have to set up it, it does not come automatically
After we merge an MR for the provider, or we have a webhook call from a consumer, the following flow will happen.
CI pipeline of merging to master for a Pact Provider
Again, this is similar to the feature CI flow, the addition here is that after the test is run, the provider will publish the result of the verification to the Pact Broker, so it will add it to the Pact Matrix. This is very useful for the deployment of CI flow. This publishing of the result is what will add green or red to the row in the Pact Broker UI that we showed in the first image.
If it is green, means that the latest contract is published and verified. We can deploy it.
Can I Deploy?
Before you deploy a new version of an application to any environment, you need to know whether or not the version you’re about to deploy is compatible with the versions of the other services that already exist in that environment.
Because of that, Pact Broker has a feature called can-I-deploy that allows each service to check if a specific version can be deployed to a specific environment.
Both Consumer and Provider have to call the can-I-deploy and the process is the same for both, so the image below summarizes it.
CI pipeline of Can I deploy?
In the example above, a service (which can be a consumer or provider) is asking the Pact Broker if it can deploy version 1.0 to the DEV environment. If the response is yes, meaning that we have a valid contract, then we can safely deploy the service to the desired environment. If the answer is no. The pipeline will fail.
After deploying the service, the pipeline calls another function (record-deployment) on the Pact Broker informing it that the version was deployed. You have to always deploy the provider first and then run the can I deploy on the consumer, otherwise the consumer will not have a provider available in that environment.
In this way, we know which version of the service is in each environment and we can have as many environments as we want.
This was a bit about the CI flow of Pact testing.
Happy testing!