This tutorial explains two options to set up the Pact Broker. You can publish the Pact Contract to the Pact Broker using the pact-js framework and with Postman:
What is Pact Broker?
Pact Broker is a tool provided by the creators of the Pact framework. It facilitates storing contracts, visualizing consumers, and the verification contract status.
The reason for having a separate broker to store the contracts is because each set of tests is often written in different repositories and even different languages.
What You Will Learn:
Publish Pact Contract To Pact Broker
Before we jump into how to publish a contract, you need to make a decision on whether you want to host the Pact Broker yourself or use a hosted service such as Pactflow.
Personally, we have opted Pactflow as this offers the additional benefits as shown in the table below:
|Secure Tokens / Secrets||Yes||No|
|Webhooks||UI configurable||Manual config|
|Infrastructure as Code||Terraform||Dockerfile|
Setting up Pact Broker With Pactflow
Pactflow provides a free option that will only charge you after the 180 month’s trial (as of May 2020), that’s 10 and a half years.
- Register your email address with Pactflow (note you can always add additional users later).
- Set up the company information and subdomain for your Pact Broker.
- You should now receive an e-mail with your temporary username and password.
- Navigate to your subdomain, (here is my subdomain) and log in. If this was successful, you should see the example app with a contract already setup.
We’ll look at how to verify against contracts within Pactflow later in the tutorial.
Setting up Pact Broker With Docker (docker-compose)
Pact offers docker images to easily spin up your own Pact Broker in seconds with docker-compose. The github repository explains how this can be done, let’s go into detail on this later.
Some additional steps that are added to ensure that the service is stable are given below:
- Add “restart: always” to the docker-compose services.
- Launch docker-compose on the server using the `-d` detached argument to allow it to run in the background.
Publishing Contract With pact-js
The Pact Broker Token shown above is stored in Pactflow under settings. Screenshots are shown below. Make sure that you are using the CI token that has Read and Writes permissions.
Probably secrets and passwords should not be stored in git, therefore a `.env` file should be used and referenced within the code with something as shown below.
Along with the “publishVerificationResult” value, you don’t want to be verifying contracts in your local environment. Therefore another environment variable should be set, as shown below.
Now the contract can be published directly in the code.
Publishing Contract With Postman
Usually, to verify the first contract, we use Postman to ensure that the broker is set up correctly. Postman has also been used when the consumers were being slow to adopt Pact within their team, so we published the contract to the Pact Broker and asked the consumer team to verify if they are happy with the contract.
This enabled us as the provider team to verify against the contract and have more confidence in our deployments. Also when the consumer team was ready to adopt Pact they already had a working example to use.
The steps for publishing Postman are given below:
#1) PUT: Construct the request
- Navigate to the subdomain
- Provider name
- Consumer name
#2) Authorization: Add the bearer token (which is equivalent to the API token as mentioned above)
#3) Include the Pact JSON as the body (the JSON can be copied directly into the body field, thereby making sure to set the Content: Type header to “application/json”).
Sharing Pacts With API Providers
Once your contracts have been published, the provider can retrieve the Pact contract by requesting the Pact Broker URL with:
Usually, you will want to verify with a specific version of the API. For example, in a microservices architecture, the consumer team is constantly making changes to the information that they require from the API.
Alongside this, the API provider is making changes at the same time, and they will need to verify against the version that is currently deployed to production as this will ensure a seamless deployment.
Finally, you have a Pact Broker with a published contract, in the next tutorial we will look at how to write your provider test by wrapping a .Net Core API, pulling the latest contract, and verifying against the local API.
The Pact framework is not only valuable at the start of your project, in a consumer-driven way, but the benefit of visualizing your consumers with the Pact Broker is definitely a key contributor to using this tool.
Also, the ability to better understand consumer interactions and how the API is actually being used can often be lost in translation and can result in a production issue that might happen. This leads to hours of debugging and trawling through the application logs.
In this tutorial, we have learned two different options to set up your Pact Broker. You have published your contract using the pact-js framework and also with Postman.
At this point, you need to think about aligning your versions across the microservices and also naming your providers consistently to create an easy to read and understandable Pact Broker network.