pact 1.0.30 → 1.0.31

data/.gitignore

@@ -27,3 +27,4 @@ spec/pacts
 .ruby-version
 log
 .idea
+reports

data/.travis.yml

@@ -2,7 +2,7 @@ language: ruby
 rvm:
   - 1.9.3
   - 2.0.0
+  - 2.1.0
   - jruby-19mode
   - jruby-20mode
-  - ruby-head
-  - jruby-head
+  - jruby-head

data/Gemfile.lock

@@ -8,7 +8,6 @@ PATH
       rack-test (~> 0.6.2)
       randexp (~> 0.1.7)
       rspec (~> 2.12)
-      thin
       thor
       webrick
 
@@ -27,9 +26,7 @@ GEM
     coderay (1.0.9)
     crack (0.4.1)
       safe_yaml (~> 0.9.0)
-    daemons (1.1.9)
     diff-lcs (1.2.4)
-    eventmachine (1.0.3)
     fakefs (0.4.2)
     find_a_port (1.0.1)
     hashie (2.0.5)
@@ -59,10 +56,6 @@ GEM
     rspec-mocks (2.14.3)
     safe_yaml (0.9.5)
     slop (3.4.6)
-    thin (1.6.1)
-      daemons (>= 1.0.9)
-      eventmachine (>= 1.0.0)
-      rack (>= 1.0.0)
     thor (0.18.1)
     thread_safe (0.1.3)
       atomic

data/README.md

@@ -2,7 +2,7 @@
 
 Define a pact between service consumers and providers, enabling "consumer driven contract" testing.
 
-Pact provides an RSpec DSL for service consumers to define the requests they will make to a service provider and the responses they expect back. These expectations are used in the consumers specs to provide a mock service provider. The interactions are recorded, and played back in the service provider specs to ensure the service provider actually does provide the response the consumer expects.
+Pact provides an RSpec DSL for service consumers to define the HTTP requests they will make to a service provider and the HTTP responses they expect back. These expectations are used in the consumers specs to provide a mock service provider. The interactions are recorded, and played back in the service provider specs to ensure the service provider actually does provide the response the consumer expects.
 
 This allows testing of both sides of an integration point using fast unit tests.
 
@@ -17,7 +17,25 @@ Travis CI Status: [![travis-ci.org Build Status](https://travis-ci.org/realestat
 * Expected interactions are verified to have actually occurred in the consumer specs.
 * The mocked responses are verified to be valid by replaying the interactions against the provider codebase.
 * Rake verification tasks allow a pacts at one or more URIs to be checked against a given service provider codebase.
-* Different versions of a consumer/provider pair can be easily tested against each other, allowing confidence when deploying new versions of each (see the pact_broker and pact_broker-client gems).
+* Different versions of a consumer/provider pairs can be easily tested against each other, allowing confidence when deploying new versions of each (see the pact_broker and pact_broker-client gems).
+
+## How does it work?
+
+1. In the specs for the provider facing code in the consumer project, expectations are set up on a mock service provider.
+1. When the specs are run, the requests, and their expected responses, are written to a "pact" file.
+1. The requests in the pact file are later replayed against the provider, and the actual responses are checked to make sure they match the expected responses.
+
+## Why is developing and testing with pacts better than using integration tests?
+
+* Faster execution.
+* No need to manage starting and stopping multiple processes.
+* Reliable responses from mock service provider reduce likelihood of flakey tests.
+* Only one component is being tested at a time, making the causes of test failures easier to identify.
+* Design of service provider is improved by considering first how the data is actually going to be used, rather than how it is most easily retrieved and serialised.
+
+## Google users group
+
+https://groups.google.com/forum/#!forum/pact-support
 
 ## Installation
 
@@ -35,12 +53,12 @@ Imagine a model class that looks something like this. The attributes for a Somet
 class SomethingModel
   attr_reader :name
 
-  def intialize name
+  def initialize name
     @name = name
   end
 
   def == other
-    other.is_a?(Something) && other.name == name
+    other.is_a?(SomethingModel) && other.name == name
   end
 end
 ```
@@ -92,6 +110,8 @@ describe MyServiceProviderClient, :pact => true do
     # Configure your client to point to the stub service on localhost using the port you have specified
     MyServiceProviderClient.base_uri 'localhost:1234'
   end
+  
+  subject { MyServiceProviderClient.new }
 
   describe "get_something" do
     before do
@@ -107,7 +127,7 @@ describe MyServiceProviderClient, :pact => true do
     end
 
     it "returns a Something" do
-      expect(MyServiceProviderClient.get_something).to eq(SomethingModel.new('A small something'))
+      expect(subject.get_something).to eq(SomethingModel.new('A small something'))
     end
 
   end
@@ -201,7 +221,7 @@ Yay! Your provider now honours the pact it has with your consumer. You can now h
 
 ### Using provider states
 
-Having different service provider states allows you to test the same request with different expected responses.
+Provider states allow different fixtures to be loaded on the provider to allow you to test the same request with different expected responses.
 
 For example, some code that creates the pact in a consumer project might look like this:
 
@@ -218,9 +238,19 @@ my_service.
   given("a thing does not exist").
    upon_receiving("a request for a thing").
       with(method: 'get', path: '/thing').
-        will_respond_with(status: 404, :body => {error: "There is no thing :("} )
+        will_respond_with(status: 404)
+
+        ...
+
+my_service.
+  given("an error occurs while retrieving a thing").
+   upon_receiving("a request for a thing").
+      with(method: 'get', path: '/thing').
+        will_respond_with(status: 500, :body => {message: "An error occurred"}, :headers => { 'Content-Type' => 'application/json'} )
 ```
 
+
+
 To define service provider states that create the right data for "a thing exists" and "a thing does not exist", write the following in the service provider project. (The consumer name here must match the name of the consumer configured in your consumer project for it to correctly find these provider states.)
 
 
@@ -241,6 +271,12 @@ Pact.provider_states_for 'My Service Consumer' do
   provider_state "a thing does not exist" do
     no_op # If there's nothing to do because the state name is more for documentation purposes, you can use no_op to imply this.
   end
+
+  provider_state "an error occurs while retrieving a thing" do
+    set_up do
+      ThingRepository.stub(:find).and_raise("An error occurred!")
+    end
+  end
 end
 
 ```
@@ -329,63 +365,24 @@ To execute a subset of the specs when running any of the pact verification tasks
 
     $ PACT_DESCRIPTION="a request for something" PACT_PROVIDER_STATE="something exists" rake pact:verify
 
-### Running a standalone mock server
-
-A pact service can be run locally and is really useful for debugging purposes.
+See [Frequently Asked Questions](https://github.com/realestate-com-au/pact/blob/master/documentation/faq.md) and [Rarely Asked Questions](https://github.com/realestate-com-au/pact/blob/master/documentation/raq.md) and [Terminology](https://github.com/realestate-com-au/pact/blob/master/documentation/terminology.md) for more information.
 
-    $ bundle exec pact service -p <port-num>
 
-The service prints messages it recieves to stdout which can be really useful
-when diagnosing issues with pacts.
+## Related Gems
 
-### To run your consumer app as a process during your consumer specs
+[Pact Provider Proxy](https://github.com/bethesque/pact-provider-proxy) - Verify a pact against a running server, allowing you to use pacts with a provider of any language.
 
-Eg. for Capybara tests
+[Pact Broker](https://github.com/bethesque/pact_broker) - A pact repository. Provides endpoints to access published pacts, meaning you don't need to use messy CI URLs in your codebase. Enables cross testing of prod/head versions of your consumer and provider, allowing you to determine whether the head version of one is compatible with the production version of the other. Helps you to answer that ever so important question, "can I deploy without breaking all the things?"
 
-```ruby
-Pact.service_consumer "My Consumer" do
-  app my_consumer_rack_app
-  port 4321
-end
-```
-
-### Handling multiple headers with the same name
-
-RFC 2616 states that two headers with the same name can interpreted as a single header with two comma-separated values. This is the safest way to specify multiple headers with the same name, as Rack will only pass the last value through when they are defined separately (see https://github.com/rack/rack/issues/436).
-
-```ruby
-my_service_provider.
-  .given("it is RFC 2616 compliant")
-  .upon_receiving("a request with a header with commas separated values")
-  .with( method: :get, path: '/', headers: {'X-Request-Multival' => "A, B"} )
-  .will_respond_with(
-    status: 200, headers: {'X-Response-Multival' => "C, D"}
-  )
-
-```
-
-### Pact file write mode
-
-By default, the pact file will be overwritten (started from scratch) every time any rspec runs any spec using pacts. This means that if there are interactions that haven't been executed in the most recent rspec run, they are effectively removed from the pact file. If you have long running pact specs (e.g. they are generated using the browser with Capybara) and you are developing both consumer and provider in parallel, or trying to fix a broken interaction, it can be tedius to run all the specs at once. In this scenario, you can set the pactfile_write_mode to :update. This will keep all existing interactions, and update only the changed ones, identified by description and provider state. The down side of this is that if either of those fields change, the old interactions will not be removed from the pact file. As a middle path, you can set pactfile_write_mode to :smart. This will use :overwrite mode when running rake (as determined by a call to system using 'ps') and :update when running an individual spec.
-
-### To use RSpec hooks for pact:verify
-
-The pact:verify RSpec examples have the metadata `{:pact => :verify}` defined. You can add RSpec hooks using a filter as shown here:
-
-```ruby
-RSpec.configure do | config |
-  config.before :each, :pact => :verify do
-    # Your code here
-  end
-end
-```
+[Pact Broker Client](https://github.com/bethesque/pact_broker-client) - Contains rake tasks for publishing pacts to the pact_broker.
 
-See https://www.relishapp.com/rspec/rspec-core/docs/hooks/filters for more information.
+[Shokkenki](https://github.com/brentsnook/shokkenki) - Another Consumer Driven Contract gem written by one of Pact's original authors, Brent Snook.
 
 ## TODO
 
 Short term:
 - FIX EXAMPLE!!!
+- Support hash of query params
 
 Long term:
 - Provide more flexible matching (eg the keys should match, and the classes of the values should match, but the values of each key do not need to be equal). This is to make the pact verification less brittle.

data/Rakefile

@@ -1,22 +1,4 @@
-require 'bundler/gem_helper'
-module Bundler
-  class GemHelper
-    def install
-      desc "Build #{name}-#{version}.gem into the pkg directory"
-      task 'build' do
-        build_gem
-      end
-
-      desc "Build and install #{name}-#{version}.gem into system gems"
-      task 'install' do
-        install_gem
-      end
-
-      GemHelper.instance = self
-    end
-  end
-end
-Bundler::GemHelper.install_tasks
+require "bundler/gem_tasks"
 require 'rspec/core/rake_task'
 
 Dir.glob('lib/tasks/**/*.rake').each { |task| load task }
@@ -25,9 +7,3 @@ RSpec::Core::RakeTask.new(:spec)
 
 task :default => [:spec, :spec_with_active_support, 'pact:tests']
 
-desc "Release to REA gems host"
-task :publish => :build do
-  gem_file = "pkg/pact-#{Pact::VERSION}.gem"
-  require 'geminabox-client'
-  Geminabox::Client.new('http://rea-rubygems').upload(gem_file)
-end

data/documentation/faq.md

@@ -0,0 +1,45 @@
+# Frequently asked questions
+
+## How can I verify a pact against a non-ruby provider?
+
+You can verify a pact against any running server, regardless of language, using [pact-provider-proxy](https://github.com/bethesque/pact-provider-proxy).
+
+There is also a JVM version of pact under development. Have a look at [pact-jvm](https://github.com/DiUS/pact-jvm), the that contains the equivalent of pact/consumer and pact/provider.
+
+### How can I create a pact for a consumer that is not ruby or on the JVM?
+
+Become famous, and write a pact-consumer library yourself! Then let us know about it so we can put a link to it in the documentation.
+
+### How can I specify hooks to be executed before/after all examples for pact:verify?
+
+The pact:verify RSpec examples have the metadata `{:pact => :verify}` defined. You can add RSpec hooks using a filter as shown here:
+
+```ruby
+RSpec.configure do | config |
+  config.before :each, :pact => :verify do
+    # Your code here
+  end
+end
+```
+
+See https://www.relishapp.com/rspec/rspec-core/docs/hooks/filters for more information.
+
+### How can I run my consumer UI during my consumer specs so I can execute the tests using a browser?
+
+Eg. for Capybara tests
+
+```ruby
+Pact.service_consumer "My Consumer" do
+  app <your rack app here>
+  port 4321
+end
+```
+
+### Should the database or any other part of the provider be stubbed?
+
+This is a hotly debated issue.
+
+The pact authors' experience with using pacts to test microservices has been that using the set_up hooks to populate the database, and running pact:verify with all the real provider code has worked very well, and gives us full confidence that the end to end scenario will work in the deployed code.
+
+However, if you have a large and complex provider, you might decide to stub some of your application code. If you do, remember to add your own "verification" of your stubbed methods - write another test that will break if the behaviour of the stubbed methods changes.
+

data/documentation/raq.md

@@ -0,0 +1,39 @@
+# Rarely asked questions
+
+### How can I run a standalone mock server?
+
+By default, a mock service will be started automatically by the pact gem when running the consumer tests. A standalone mock service can be run locally and is useful for debugging purposes.
+
+```ruby
+Pact.service_consumer "My Service Consumer" do
+  has_pact_with "My Service Provider" do
+    mock_service :my_service_provider do
+      port <port-num>
+      standalone true #Tell the pact gem not to automatically start the mock service
+    end
+  end
+end
+```
+    $ bundle exec pact service -p <port-num>
+
+The service prints messages it recieves to stdout which can be really useful
+when diagnosing issues with pacts.
+
+### How can I specify multiple headers with the same name?
+
+RFC 2616 states that two headers with the same name can interpreted as a single header with two comma-separated values. This is the safest way to specify multiple headers with the same name, as Rack will only pass the last value through when they are defined separately (see https://github.com/rack/rack/issues/436).
+
+```ruby
+my_service_provider.
+  .given("it is RFC 2616 compliant")
+  .upon_receiving("a request with a header with commas separated values")
+  .with( method: :get, path: '/', headers: {'X-Request-Multival' => "A, B"} )
+  .will_respond_with(
+    status: 200, headers: {'X-Response-Multival' => "C, D"}
+  )
+
+```
+
+### What is this pact file write mode?
+
+By default, the pact file will be overwritten (started from scratch) every time any rspec runs any spec using pacts. This means that if there are interactions that haven't been executed in the most recent rspec run, they are effectively removed from the pact file. If you have long running pact specs (e.g. they are generated using the browser with Capybara) and you are developing both consumer and provider in parallel, or trying to fix a broken interaction, it can be tedius to run all the specs at once. In this scenario, you can set the pactfile_write_mode to :update. This will keep all existing interactions, and update only the changed ones, identified by description and provider state. The down side of this is that if either of those fields change, the old interactions will not be removed from the pact file. As a middle path, you can set pactfile_write_mode to :smart. This will use :overwrite mode when running rake (as determined by a call to system using 'ps') and :update when running an individual spec.

data/documentation/terminology.md

@@ -0,0 +1,25 @@
+# Terminology
+
+### Service Consumer
+
+A component that initiates a HTTP request to another component (the service provider). Note that this does not depend on the way the data flows - whether it is a GET or a PUT/POST/PATCH, the consumer is the initiator of the HTTP request.
+
+### Service Provider
+
+A server that responds to an HTTP request from another component (the service consumer).
+
+### Mock Service Provider
+
+Used by tests in the consumer project to mock out the actual service provider, meaning that integration-like tests can be run without requiring the actual service provider to be available.
+
+### Pact file
+
+A file containing the JSON serialised requests and responses that were defined in the consumer tests.
+
+### Pact verification
+
+To verify a pact, the requests contained in a pact file are replayed against the provider code, and the responses returned are checked to ensure they match those expected in the pact file.
+
+## Provider state
+
+A name describing a "state" (like a fixture) that the provider should be in when a given request is replayed against it. Eg. "there is an alligator called Mary" or "there are no alligators". A provider state name is specified when writing the consumer specs, then, when the pact verification is set up in the provider, the same name will be used to identify the set up code block that should be run before the request is executed.

data/example/animal-service/Gemfile

@@ -1,7 +1,5 @@
 source 'https://rubygems.org'
 
-gem 'bundler', '~> 1.3.0'
-
 group :development, :test do
   gem 'rspec'
   gem 'pact', path: '../../'
@@ -10,5 +8,7 @@ end
 
 gem 'rake'
 gem 'rack', '~>1.5.2'
-gem 'json', '~>1.6.8'
-gem 'httparty'
+gem 'json', '~>1.6'
+gem 'sqlite3'
+gem 'sequel'
+gem 'sinatra'

data/example/animal-service/Gemfile.lock

@@ -1,39 +1,35 @@
 PATH
   remote: ../../
   specs:
-    pact (1.0.9)
-      awesome_print (~> 1.1.0)
+    pact (1.0.30)
+      awesome_print (~> 1.1)
       find_a_port (~> 1.0.1)
-      hashie (~> 2.0)
       json
       rack-test (~> 0.6.2)
       randexp (~> 0.1.7)
       rspec (~> 2.12)
       thin
       thor
+      webrick
 
 GEM
   remote: https://rubygems.org/
   specs:
-    awesome_print (1.1.0)
+    awesome_print (1.2.0)
     coderay (1.0.9)
     daemons (1.1.9)
     diff-lcs (1.2.4)
     eventmachine (1.0.3)
     find_a_port (1.0.1)
-    hashie (2.0.5)
-    httparty (0.11.0)
-      multi_json (~> 1.0)
-      multi_xml (>= 0.5.2)
     json (1.6.8)
     method_source (0.8.2)
-    multi_json (1.8.0)
-    multi_xml (0.5.5)
     pry (0.9.12.2)
       coderay (~> 1.0.5)
       method_source (~> 0.8)
       slop (~> 3.4)
     rack (1.5.2)
+    rack-protection (1.5.1)
+      rack
     rack-test (0.6.2)
       rack (>= 1.0)
     rake (10.1.0)
@@ -46,22 +42,31 @@ GEM
     rspec-expectations (2.14.2)
       diff-lcs (>= 1.1.3, < 2.0)
     rspec-mocks (2.14.3)
+    sequel (4.5.0)
+    sinatra (1.4.4)
+      rack (~> 1.4)
+      rack-protection (~> 1.4)
+      tilt (~> 1.3, >= 1.3.4)
     slop (3.4.6)
-    thin (1.5.1)
+    sqlite3 (1.3.8)
+    thin (1.6.1)
       daemons (>= 1.0.9)
-      eventmachine (>= 0.12.6)
+      eventmachine (>= 1.0.0)
       rack (>= 1.0.0)
     thor (0.18.1)
+    tilt (1.4.1)
+    webrick (1.3.1)
 
 PLATFORMS
   ruby
 
 DEPENDENCIES
-  bundler (~> 1.3.0)
-  httparty
-  json (~> 1.6.8)
+  json (~> 1.6)
   pact!
   pry
   rack (~> 1.5.2)
   rake
   rspec
+  sequel
+  sinatra
+  sqlite3