Enables your consumer driven contracts workflow
Clone or download
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github docs: updated issue template Apr 10, 2018
config chore: add config for postgres running on docker on port 5433 Aug 5, 2018
db feat: eager load latest version for /pacticipants resource Aug 27, 2018
example feat: add LogQuietener to example config.ru Oct 28, 2018
lib chore(release): version 2.27.5 Nov 15, 2018
public feat: update matrix UI to allow _all_ versions with a particular tag … Apr 19, 2018
script chore: ensure script/db-spec.sh exits with correct status code Oct 3, 2018
spec fix: handle race conditions when creating a pacticipant Nov 15, 2018
tasks fix: ensure bundle install for pact_broker:dev:setup uses correct Gem… Oct 23, 2018
vendor/hal-browser feat(hal browser): use name over title in embedded resource heading Sep 18, 2017
.codeclimate.yml chore: correct codeclimate.yml format Mar 5, 2018
.csslintrc chore(build): Add code climate config files Jul 3, 2017
.eslintignore chore(build): Add code climate config files Jul 3, 2017
.eslintrc.yml chore(build): Add code climate config files Jul 3, 2017
.gitignore chore: update .gitignore May 17, 2018
.rspec WIP webhooks Aug 3, 2014
.rubocop.yml chore(build): Add code climate config files Jul 3, 2017
.ruby-version feat(http): set http options globally Feb 25, 2018
.travis.yml chore: disabled backwards compatibility tests until I can work out wh… Oct 4, 2018
CHANGELOG.md chore(release): version 2.27.5 Nov 15, 2018
CONTRIBUTING.md chore: fix markdown links in CONTRIBUTING.md Aug 7, 2018
DEVELOPER_DOCUMENTATION.md docs: update DEVELOPER_DOCUMENTATION.md Aug 5, 2018
DEVELOPER_SETUP.md fix: Fix some invalid HTML Oct 21, 2018
Gemfile chore(mysql): remove MySQL dep for local development Sep 20, 2018
LICENSE.txt Added copyright year and owner. Mar 23, 2017
README.md docs: update readme to remove now inaccurate comment about MySQL's la… Sep 7, 2018
RELEASING.md chore: add release script Nov 1, 2017
Rakefile Added more tests for VersionRepository, using database_cleaner gem Oct 14, 2014
UPGRADING.md test: improved db backwards compatiblity tests Sep 10, 2017
config.ru style: refactor relationship controller, pages and css to index Nov 11, 2017
pact_broker.gemspec fix: ensure latest version of rack is used to avoid vulnerability CVE… Nov 15, 2018
pact_broker_client-pact_broker.json Rename provider_state to providerState in pact files. May 8, 2017

README.md

Pact Broker

Gem Version Build Status Join the chat at https://gitter.im/pact-foundation/pact_broker Code Climate Test Coverage Issue Count

The Pact Broker is an application for sharing for 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.

Why do I need one?

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:

  • allows you to release customer value quickly and confidently by deploying your services independently and avoiding the bottleneck of integration tests
  • solves the problem of how to share contracts and verification results between consumer and provider projects
  • tells you which versions of your applications can be deployed safely together
  • automatically versions your contracts
  • allows you to ensure backwards compatibility between multiple consumer and provider versions (eg. in a mobile or multi-tenant environment)
  • provides API documentation of your applications 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 API browser for navigating the API.
  • Autogenerated documentation for each pact.
  • Dynamically generated network diagrams so you can visualise your microservice network.
  • Displays provider verificaton results so you know if you can deploy safely.
  • Provides a "matrix" of compatible consumer and provider versions, so you know which versions can be safely deployed together.
  • Provides badges to display pact verification statuses in your READMEs.
  • Enables an application version to be tagged (ie. "prod", "feat/customer-preferences") to allow repository-like workflows.
  • Provides webhooks to trigger actions when pacts change eg. run provider build, notify a Slack channel.
  • View diffs between Pact versions so you can tell what expectations have changed.
  • Docker Pact Broker
  • A CLI for encorporating the Pact workflow into your continuous integration process.

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 libries 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

The following funcationality is in beta release. Your feedback would be appreciated.

  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

  • Check the wiki first.
  • See if there is an existing or closed issue and raise a new issue if not.
  • See if there is an existing question on stackoverflow tagged with pact-broker, and ask a new question if not.
  • Have a chat to us on the Pact gitter.
  • Tweet us at @pact_up on the twitters.

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 navigate 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 2.2.0 or later and bundler >= 1.12.0
    • Windows users: get a Rails/Ruby installer from RailsInstaller and run it
    • unix users just use your package manager
  • Run git clone git@github.com:pact-foundation/pact_broker.git && cd pact_broker/example
  • Run bundle install
  • Run bundle exec rackup -p 8080 (this will use a Sqlite database. If you want to try it out with a Postgres database, see the README in the example directory.)
  • 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

Hosted

In a hurry? Hate having to run your own infrastructure? Check out the Hosted Pact Broker - it's fast, it's secure and it's free!

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

  • Are you sure you don't just want to use the Pact Broker Docker image? No Docker at your company yet? Ah well, keep reading.
  • Create a PostgreSQL (recommended) or MySQL (not as recommended because of @bethesque's personal prejudices, but still fully supported) database.
  • To ensure you're on a supported version of the database that you choose, check the travis.yml file to see which versions we're currently running our tests against.
  • If you're using PostgreSQL (did we mention this was recommended!) you'll find the database creation script in the example/config.ru.
  • Install ruby 2.4 or later and the latest version of bundler (if you've come this far, I'm assuming you know how to do both of these. Did I mention there was a Docker image?)
  • Copy the pact_broker directory from the Pact Broker Docker project. This will have the recommended settings for database connections, logging, basic auth etc. Note that the Docker image uses Phusion Passenger as the web application server in front of the Pact Broker Ruby application, which is the recommended set up.
  • Modify the config.ru and Gemfile as desired (eg. choose database driver gem, set your database credentials. Use the "pg" gem if using Postgres and the "mysql2" gem if using MySQL)
    • example Sequel configuration for postgres {adapter: "postgres", database: "pact_broker", username: 'pact_broker', password: 'pact_broker', :encoding => 'utf8'}
    • example Sequel configuration for mysql {adapter: "mysql2", database: "pact_broker", username: 'pact_broker', password: 'pact_broker', :encoding => 'utf8'} `
  • 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. You'll need to read up on the documentation for these yourself as it is beyond the scope of this documentation. See the wiki for instructions on using a reverse proxy with SSL.
  • Ensure the environment variable RACK_ENV is set to production.
  • Deploy to your location of choice.

Upgrading

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