Home

Awesome

Pact Broker

Gem Version Build status Join the chat at https://pact-foundation.slack.com/

The Pact Broker is an application for sharing of consumer driven contracts and verification results. It is optimised for use with "pacts" (contracts created by the Pact framework), but can be used for any type of contract that can be serialized to JSON.

<br/> <a href="https://pactflow.io/?utm_source=github&utm_campaign=pact_broker_intro"><img src="docs/images/Pactflow logo - black small.png"></a> <br/>

You can try out a Pact Broker for free at <a href="https://pactflow.io/?utm_source=github&utm_campaign=pact_broker_intro"/>pactflow.io</a>. Built by a group of core Pact maintainers, PactFlow is a fork of the OSS Pact Broker with extra goodies like an improved UI, field level verification results and federated login.

Why do I need a Pact Broker?

Contract testing is an alternative approach to traditional integration testing that gives you tests that are quicker to execute, and that are more maintainable at scale. One down side of the approach is that the important information that would be available all in one place at the end of an integration test suite execution (that is, the version numbers of all the applications that were tested together, and whether the tests passed or failed) is now spread out across many different builds. The Pact Broker is a tool that brings all this information back together again, and allows you to deploy with safety.

It:

Features:

How would I use the Pact Broker?

Step 1. Consumer CI build

  1. The consumer project runs its tests using the Pact library to provide a mock service.
  2. While the tests run, the mock service writes the requests and the expected responses to a JSON "pact" file - this is the consumer contract.
  3. The generated pact is then published to the Pact Broker. Most Pact libraries will make a task available for you to do this easily, however, at its simplest, it is a PUT to a resource that specifies the consumer name and application version, and the provider name. eg http://my-pact-broker/pacts/provider/Animal%20Service/consumer/Zoo%20App/version/1.0.0 (Note that you are specifying the consumer application version in the URL, not the pact version. The broker will take care of versioning the pact behind the scenes when its content changes. It is expected that the consumer application version will increment with every CI build.)
  4. When a pact is published, a webhook in the Pact Broker kicks off a build of the provider project if the pact content has changed since the previous version.

Step 2. Provider CI build

  1. The provider has a verification task that is configured with the URL to retrieve the latest pact between itself and the consumer. eg http://my-pact-broker/pacts/provider/Animal%20Service/consumer/Zoo%20App/latest.
  2. The provider build runs the pact verification task, which retrieves the pact from the Pact Broker, replays each request against the provider, and checks that the responses match the expected responses.
  3. If the pact verification fails, the build fails. The Pact Broker CI Nerf Gun magically determines who caused the verification to fail, and shoots them.
  4. The results of the verification are published back to the Pact Broker by the pact verification tool, so the consumer team will know if the code they have written will work in real life.

If you don't have a Pact Broker CI Nerf Gun, you'll probably want to read about using pact when the consumer and provider are being written by different teams.

Step 3. Back to the Consumer CI build

  1. The Consumer CI determines if the pact has been verified by running pact-broker can-i-deploy --pacticipant CONSUMER_NAME --version CONSUMER_VERSION ... (see documentation here)
  2. If the pact has been verified, the deployment can proceed.

Read more about how to use the Pact Broker in the overview on the wiki page.

Documentation

See the wiki for documentation on the Pact Broker. Please read the overview page first to get an understanding of the HTTP resources in the broker, and how they relate to each other.

Support

Screenshots

Index


<img src="https://raw.githubusercontent.com/wiki/pact-foundation/pact_broker/images/index.png"/>

Autogenerated documentation

Paste the pact URL into a browser to view a HTML version of the pact.


<img src="https://raw.githubusercontent.com/wiki/pact-foundation/pact_broker/images/autogenerated_documentation.png"/>

Network diagram


<img src="https://raw.githubusercontent.com/wiki/pact-foundation/pact_broker/images/network_diagram.png"/>

HAL browser

Use the embedded HAL browser to navigate the API.


<img src="https://raw.githubusercontent.com/wiki/pact-foundation/pact_broker/images/hal_browser.png"/>

HAL documentation

Use the HAL browser to view documentation as you browse.


<img src="https://raw.githubusercontent.com/wiki/pact-foundation/pact_broker/images/hal_documentation.png"/>

Usage

To have a play around on your local machine

Using Docker Compose

Download a copy of the example Docker Compose file from the Pact Broker Docker repository and run:

docker compose up

Then open a browser at http://localhost:9292.

Using Ruby

For reals

Hosted

In a hurry? Hate having to run your own infrastructure? Check out pactflow.io - it's fast, it's secure and it's free to trial!

Container solutions

You can use the Pact Broker Docker image or Terraform on AWS. See the wiki for instructions on using a reverse proxy with SSL.

Rolling your own

Upgrading

Please read the UPGRADING.md documentation before upgrading your Pact Broker, for information on the supported upgrade paths.

Versioning

The Pact Broker follows the semantic versioning scheme.