The Pact Broker enables you to share your pacts between projects, and make them useful for people too.
JavaScript Ruby HTML CSS Shell
Latest commit 4f67f1c Jan 18, 2017 @bethesque Releasing version 1.13.0
Permalink
Failed to load latest commit information.
config Created nice interface for making a pact_broker instance Apr 26, 2014
db Revert "migration 17 now runs against sqlite3 backend" Dec 1, 2016
example Added extra pact version to example database so that the diff feature… Nov 8, 2016
lib Releasing version 1.13.0 Jan 18, 2017
public Stop pacticipant names wrapping on relationships page Jan 13, 2015
script Added support for JSON contracts that are not in the Pact format (e.g… Mar 20, 2015
spec Adds the spec for pact versions endpoint, and corrects the file name … Jan 18, 2017
tasks Moved json_content into separate table. Nov 16, 2014
vendor/hal-browser Added link from HAL browser to home Dec 13, 2014
.gitignore Add ruby 2.1.3 and set as default Sep 17, 2015
.rspec WIP webhooks Aug 3, 2014
.ruby-version Update default dev ruby version to 2.3.1 Jun 27, 2016
.travis.yml Removed ruby 2.1 build as it is failing Nov 9, 2016
CHANGELOG.md Releasing version 1.13.0 Jan 18, 2017
Gemfile Moved all web hook validation into contracts. Currently failing when … Oct 14, 2014
LICENSE.txt Create LICENSE.txt Aug 23, 2015
README.md remove references to bundler 1.13 not working Nov 29, 2016
RELEASING.md Update release notes Aug 12, 2016
Rakefile Added more tests for VersionRepository, using database_cleaner gem Oct 14, 2014
bethtest.rb Made it recursive to keep @thetrav happy. May 9, 2014
config.ru fix missing images Sep 23, 2016
pact_broker.gemspec Updated trailblazer gem to ~>0.3.0 and fixed pact diff spec. Nov 8, 2016
pact_broker_client-pact_broker.json Adding endpoint to publish pacts Nov 3, 2013

README.md

Pact Broker

Build Status Join the chat at https://gitter.im/bethesque/pact_broker

The Pact Broker provides a repository for consumer driven contracts created using the pact gem.

It:

  • solves the problem of how to share pacts between consumer and provider projects
  • allows you to decouple your service release cycles
  • provides API documentation that is guaranteed to be up-to date
  • shows you real examples of how your services interact
  • allows you to visualise the relationships between your services

Features:

  • A RESTful API for publishing and retrieving pacts.
  • An embedded HAL browser for navigating the API.
  • Autogenerated documentation for each pact.
  • Dynamically generated network diagrams.
  • Enables a pact version to be tagged (ie. "prod") so a provider can verify itself against a fixed version of a pact to ensure backwards compatibility.
  • Webhooks to trigger a provider build when a consumer publishes a change to a pact.
  • Tracks changes between Pact versions so you can tell when a consumer has changed its expectations.
  • Docker Pact Broker

Travis CI Status: Build Status

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. This is simply a PUT to a resource that specifies the consumer name and version, and the provider name. eg http://my-pact-broker/pacts/provider/Animal%20Service/consumer/Zoo%20App/version/1.0.0

Step 2. Provider CI build

  1. The provider has a verification task that is configured with the URL to retrieve the dynamically calculated latest pact between itself and the consumer. eg http://my-pact-broker/pacts/provider/Animal%20Service/consumer/Zoo%20App/latest. The "latest" version is determined by the Pact Broker by inspecting the consumer version number specified when each pact was published.
  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.

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.

Documentation

See the Pact Broker Client for documentation on how to publish a pact to the Pact Broker, and configure the URLs in the provider project.

See the wiki for documentation related to the Pact Broker itself.

Screenshots

Index


Autogenerated documentation

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


Network diagram


HAL browser

Use the embedded HAL browser to nagivate the API.


HAL documentation

Use the HAL browser to view documentation as you browse.


Usage

To have a play around on your local machine

  • Install ruby 1.9.3 or later and bundler >= 1.12.0
  • Run git clone git@github.com:bethesque/pact_broker.git && cd pact_broker/example
  • Run bundle
  • Run bundle exec rackup -p 8080
  • Open http://localhost:8080 and you should see a list containing the pact between the Zoo App and the Animal Service.
  • Click on the arrow to see the generated HTML documentation.
  • Click on either service to see an autogenerated network diagram.
  • Click on the HAL Browser link to have a poke around the API.
  • Click on the book icon under "docs" to view documentation related to a given relation.

For reals

You can use the Pact Broker Docker container or Terraform on AWS or to roll your own...

  • Create a database using a product that is supported by the Sequel gem (listed on this page http://sequel.jeremyevans.net/rdoc/files/README_rdoc.html). The migrations have been tested on MySQL and PostgreSQL - your milage will vary on other databases.
  • Note: It is recommended to use PostgreSQL as it will support JSON search features that are planned in a future release, however MySQL the other semi supported database.
  • Install ruby 1.9.3 or later and bundler >= 1.12.0
  • Copy the example directory to the location you want to install the application.
  • Modify the config.ru and Gemfile as desired (eg. choose database driver gem, set your database credentials. Use the "pg" gem if using Postgres.)
  • Please ensure you use encoding: 'utf8' in your Sequel options to avoid encoding issues.
  • For production usage, use a web application server like Phusion Passenger or Nginx to serve the Pact Broker application.
  • Deploy to your location of choice.