Verifying pacts

See Verifying Pacts for an introduction into this topic.

Using rake pact:verify

Using the pact:verify task is the most common way to verify pacts. This is where you configure the default set of pacts that your service provider should honour.

It is made available by requiring 'pact/tasks' in your Rakefile.

# In Rakefile
require 'pact/tasks'
# Remember to add it to your default Rake task
task :default => 'pact:verify'

The pacts that will be verified by the pact:verify task are configured in the pact_helper.rb file in your provider codebase.
The file must be called pact_helper.rb, however there is some flexibility in where it can be stored.
The recommended place is spec/service_consumers/pact_helper.rb.

To ensure that the latest version of the consumer pact is used each time, it is recommended that you either use a Pact Broker
or that you publish the pacts of a successful consumer build as artefacts in your CI system.

Note: Pact uses Rack::Test, and assumes that your service provider will be a Rack app. See below for options if your provider is not a Rack app.

# In specs/service_consumers/pact_helper.rb
require 'pact/provider/rspec'
# Require the provider states files for each service consumer
require 'service_consumers/provider_states_for_my_service_consumer'
Pact.service_provider "My Service Provider" do
  # Optional app configuration. Pact loads the app from config.ru by default
  # (it is recommended to let Pact use the config.ru if possible, so testing
  # conditions are closest to runtime conditions)
  app { MyApp.new }
  honours_pact_with 'My Service Consumer' do
    # This example points to a local file, however, on a real project with a continuous
    # integration box, you would publish your pacts as artifacts,
    # and point the pact_uri to the pact published by the last successful build.
    pact_uri '../path-to-your-consumer-project/specs/pacts/my_consumer-my_provider.json'
  end
  # This block is repeated for every pact that this provider should be verified against.
  honours_pact_with 'Some other Service Consumer' do
    ...
  end
end

With basic auth

To verify a pact from a URL that requires basic auth, add username and password options:

  pact_uri 'http://...', {username: '...', password: '...'}

Verifying a pact at any URL using rake pactat

You can verify a pact at any arbitrary local or remote URL using the pactat task.
This is useful when you are developing the consumer and provider concurrently, and wish to verify the pact you have just generated in the consumer code base. It will use the same pact_helper file as pact:verify.

$ rake pact:verify:at[../path-to-your-consumer-project/specs/pacts/my_consumer-my_provider.json]
$ rake pact:verify:at[http://build-box/MyConsumerBuild/latestSuccessful/artifacts/my_consumer-my_provider.json]

With basic auth, set the environment variables PACT_BROKER_USERNAME and PACT_BROKER_PASSWORD, or use the basic auth URL format, http://username:password@pactbroker.yourdomain/....

Verifying a pact stored in Amazon S3

Pact::Retreaty is a tool which provides a ultra light mechanism for
pushing and pulling pact contracts to/from S3.

Using a custom pact:verify task

To make a shortcut task for verifying a pact an arbitrary URL that you do not want to verify as part of your normal pact:verify task,
(eg. when you are developing the consumer and provider side by side, and want a shorter feedback cycle than can be provided by
by your CI box) add the following to your Rakefile. The pact.uri may be a local file system path or a remote URL.

# In Rakefile or /tasks/pact.rake
# This creates a rake task that can be executed by running
# $ rake pact:verify:dev
Pact::VerificationTask.new(:dev) do | task |
  task.uri '../path-to-your-consumer-project/specs/pacts/my_consumer-my_provider.json'
end

With basic auth, set the environment variables PACT_BROKER_USERNAME and PACT_BROKER_PASSWORD, or use the basic auth URL format, http://username:password@pactbroker.yourdomain/....

Verifying one interaction at a time

At some stage, you’ll want to be able to run your specs one at a time while you implement each feature. At the bottom of the failed pact:verify output you will see the commands to rerun each failed interaction individually. A command to run just one interaction will look like this:

$ rake pact:verify PACT_DESCRIPTION="a request for something" PACT_PROVIDER_STATE="something exists"

Verifying pacts for non-Rack apps

Ruby apps

If your app is a non-Rack Ruby app, you may be able to find a Rack adapter for it. If you can do this, then configure the app in the Pact.service_provider block to point to an instance of your adapter. Otherwise, use the pact-provider-proxy gem.

Configuring RSpec

Pact uses dynamically created RSpec specs to verify pacts. If you want to modify the behaviour of the underlying RSpec execution, you can:

1. Configure RSpec in the pact_helper using the normal RSpec.configure code.
2. Set task.rspec_opts in your custom rake VerificationTask, the same way you would with a normal RSpec rake task declaration.

For future proofing though, try to use the provider state set_up/tear_down blocks where you can, because we may swap out RSpec for custom verification code in the future.

Pact Helper location

The search paths for the pact_helper are:

[
  "spec/**/*service*consumer*/pact_helper.rb",
  "spec/**/*consumer*/pact_helper.rb",
  "spec/**/pact_helper.rb",
  "**/pact_helper.rb"]