pact 0.1.28 → 0.1.35

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    pact (0.1.28)
+    pact (0.1.35)
       awesome_print (~> 1.1.0)
       capybara (~> 2.1.0)
       find_a_port (~> 1.0.1)
@@ -37,7 +37,7 @@ GEM
     hashie (2.0.5)
     json (1.8.0)
     method_source (0.8.1)
-    mime-types (1.23)
+    mime-types (1.24)
     mini_portile (0.5.1)
     multipart-post (1.2.0)
     nokogiri (1.6.0)
@@ -55,10 +55,10 @@ GEM
       rspec-core (~> 2.14.0)
       rspec-expectations (~> 2.14.0)
       rspec-mocks (~> 2.14.0)
-    rspec-core (2.14.4)
-    rspec-expectations (2.14.0)
+    rspec-core (2.14.5)
+    rspec-expectations (2.14.2)
       diff-lcs (>= 1.1.3, < 2.0)
-    rspec-mocks (2.14.1)
+    rspec-mocks (2.14.3)
     safe_yaml (0.9.4)
     slop (3.4.5)
     thin (1.5.1)

data/README.md

@@ -3,28 +3,37 @@
 Define a pact between service consumers and providers.
 
 
-Pact provides an RSpec DSL for service consumers to define the request they will make to a service producer and the
-response they expect back. This expectation is used in the consumers specs to provide a mock producer, and is also
-played back in the producer specs to ensure the producer actually does provide the response the consumer expects.
+Pact provides an RSpec DSL for service consumers to define the request they will make to a service service provider and the
+response they expect back. This expectation is used in the consumers specs to provide a mock service provider, and is also
+played back in the service provider specs to ensure the service provider actually does provide the response the consumer expects.
 
 This allows you to test both sides of an integration point using fast unit tests.
 
+This gem is inspired by the concept of "Consumer driven contracts". See http://martinfowler.com/articles/consumerDrivenContracts.html for more information.
+
 ## Installation
 
 Put it in your Gemfile. You know how.
 
 ## Usage
 
-### Consumer project
+### Service Consumer project
 
 #### Configuration
 
+```ruby
 Pact.configure do | config |
   config.pact_dir = "???" # Optional, default is ./spec/pacts
   config.log_dir = "???" # Optional, default is ./log
-  config.logger = "??"
+  config.logger = "??" # Optional, defaults to a file logger to the configured log_dir.
   config.logger.level = Logger::DEBUG #By default this is INFO, bump this up to debug for more detailed logs
+  # Optional.
+  # The default pactfile_write_mode is "defined?(Rake) ? :overwrite : :update"
+  # This allows it to create a clean file when running rake, but only update the executed interactions when running a specific test using "rspec spec/...".
+  # This is the recommended setting.
+  config.pactfile_write_mode = :ovewrite / :update
 end
+```
 
 #### Create a Consumer (Driven) Contract
 
@@ -41,26 +50,23 @@ class SomeServiceClient
   end
 end
 
-Pact.configure do | config |
-  config.consumer do
-    name 'My Consumer'
+Pact.service_consumer "My Consumer" do
+  has_pact_with "My Provider" do
+    mock_service :my_service_provider do
+      port 1234
+    end
   end
 end
 
 # The following block creates a service on localhost:1234 which will respond to your application's queries
-# over HTTP as if it were the real "My Producer" app. It also creats a mock producer object
-# which you will use to set up your expectations. The method name to access the mock producer
-# will be what ever name you give as the service argument - in this case "my_producer"
+# over HTTP as if it were the real "My Provider" app. It also creats a mock service provider object
+# which you will use to set up your expectations. The method name to access the mock service provider
+# will be what ever name you give as the service argument - in this case "my_service_provider"
 
-Pact.with_producer "My Producer" do
-  mock_service :my_producer do
-    port 1234
-  end
-end
 
 # Use the :pact => true describe metadata to include all the pact generation functionality in your spec.
 
-describe "a pact with My Producer", :pact => true do
+describe "a pact with My Provider", :pact => true do
 
   before do
     # Configure your client to point to the stub service on localhost using the port you have specified
@@ -68,7 +74,7 @@ describe "a pact with My Producer", :pact => true do
   end
 
   it "returns something when requested" do
-    my_producer.
+    my_service_provider.
       given("something exists").
         upon_receiving("a request for something").
           with({ method: :get, path: '/something' }).
@@ -93,32 +99,26 @@ Logs will be output to the configured log dir that can be useful when diagnosing
 To run your consumer app as a process during your test (eg for a Capybara test):
 
 ```ruby
-Pact.configure do | config |
-  config.consumer do
-    name 'My Consumer'
-    app my_consumer_rack_app
-    port 4321
-  end
+Pact.service_consumer "My Consumer" do
+  app my_consumer_rack_app
+  port 4321
+end
 ```
 
-### Producer project
+### Service Provider project
 
-#### Configure your producer rack app
+#### Configure your service provider rack app
 
 ```ruby
-
-Pact.configure do | config |
-  config.producer do
-    name "My Producer"
-    app { MyApp.new }
-  end
+Pact.service_provider "My Provider" do
+  app { MyApp.new }
 end
 
 ```
 
-#### Set up the producer states
+#### Set up the service provider states
 
-Having different producer states allows you to test the same request with different expected responses.
+Having different service provider states allows 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:
 
@@ -136,16 +136,16 @@ my_service.
         will_respond_with({status: 404, :body => {error: "There is no thing :("} })
 ```
 
-To define producer states that create the right data for "a thing exists" and "a thing does not exist", write the following in the producer project.
-Note that these states have been defined only for the 'My Consumer' consumer by using the Pact.with_consumer block.
+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.
+Note that these states have been defined only for the 'My Consumer' consumer by using the Pact.provider_states_for block.
 
 
 ```ruby
 # The consumer name here must match the name of the consumer configured in your consumer project
 # for it to use these states.
 
-Pact.with_consumer 'My Consumer' do
-  producer_state "a thing exists" do
+Pact.provider_states_for 'My Consumer' do
+  provider_state "a thing exists" do
     set_up do
       # Create a thing here using your factory of choice
     end
@@ -155,7 +155,7 @@ Pact.with_consumer 'My Consumer' do
     end
   end
 
-  producer_state "a thing does not exist" do
+  provider_state "a thing does not exist" do
     set_up do
       # Well, probably not much to do here, but you get the picture.
     end
@@ -164,17 +164,17 @@ end
 
 ```
 
-If a state should be used for all consumers, the top level Pact.with_consumer can be skipped, and a global Pact.producer_state can be defined on its own. 
+If a state should be used for all consumers, the top level Pact.with_consumer can be skipped, and a global Pact.provider_state can be defined on its own. 
 
-#### Create a rake task to verify that the producer honours the pact
+#### Create a rake task to verify that the service provider honours the pact
 
-You'll need to create one or more pact:verify:xxx tasks, that allow the currently checked out producer to be tested against other versions of its consumers - most importantly, head and production.
+You'll need to create one or more pact:verify:xxx tasks, that allow the currently checked out service provider to be tested against other versions of its consumers - most importantly, head and production.
 
 Here is an example pact:verify:head task, pointing the the pact file for "some_consumer", found in the build artifacts of the latest successful build of "MY-CONSUMER" project.
 
 ```ruby
 Pact::VerificationTask.new(:head) do | pact |
-  pact.uri 'http://our_build_server/MY-CONSUMER-BUILD/latestSuccessful/artifact/Pacts/some_consumer-this_producer.json',
+  pact.uri 'http://our_build_server/MY-CONSUMER-BUILD/latestSuccessful/artifact/Pacts/some_consumer-this_service provider.json',
     support_file: './spec/consumers/pact_helper'
 end
 ```
@@ -182,20 +182,18 @@ end
 ```ruby
 # Ideally we'd like to be able to create a production task like this, but firewalls are making this tricky right now.
 Pact::VerificationTask.new(:production) do | pact |
-  pact.uri 'http://our_prod_server/pacts/some_consumer-this_producer.json',
-    support_file: './spec/consumers/pact_helper', consumer: 'some_consumer'
+  pact.uri 'http://our_prod_server/pacts/some_consumer-this_service_provider.json',
+    support_file: './spec/consumers/pact_helper'
 end
 ```
 
 The pact.uri may be a local file system path or a remote URL.
 
-The consumer is optional, and specifies which consumer namespace to use when looking up the producer states, if consumer namespaces have been used.
-
 The support_file should include the code that makes your rack app available for the rack testing framework, and should load all its dependencies (eg include spec_helper)
 
-Multiple pact.uri may be defined in the same rake task if a producer has more than one consumer.
+Multiple pact.uri may be defined in the same rake task if a service provider has more than one consumer.
 
-#### Verify that the producer honours the pact
+#### Verify that the service provider honours the pact
 
     rake pact:verify:head
     rake pact:verify # will run all verify tasks
@@ -212,18 +210,19 @@ when diagnosing issues with pacts.
 ## TODO
 
 Short term:
-- Rename ConsumerContract to ConsumerContract (Done)
+- Rename Pact to ConsumerContract (Done)
 - Simplify set up for consumer (Done)
   - Move server spawning into to the "at" method (Done)
   - automatically register before and after hooks in consumer (Done)
-- Provide before and after hooks and a place to define the app for Pact configuration in producer (remove Rspc from interface of Pact setup) (Done)
+- Provide before and after hooks and a place to define the app for Pact configuration in service provider (remove Rspc from interface of Pact setup) (Done)
   - Set_up for state
   - Tear_down for state
   - Before hook for all
   - After hook for all
-- Make producer state lookup try consumer defined state first, then fall back to global one (Done)
-- Put producer and consumer name into pact file (Done)
+- Make service provider state lookup try consumer defined state first, then fall back to global one (Done)
+- Put service provider and consumer name into pact file (Done)
 - Remove consumer name from the rake task, as it should now be able to be determined from the pact file. (Done)
+- 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.
 
 Long term:
 - Decouple Rspec from Pact and make rspec-pact gem for easy integration

data/example/zoo-app/Gemfile

@@ -0,0 +1,15 @@
+source 'https://rubygems.org'
+source 'http://rea-rubygems/'
+
+gem 'bundler', '~> 1.3.0'
+
+group :development, :test do
+  gem 'rspec'
+  gem 'pact'
+  gem 'pry'
+end
+
+gem 'rake'
+gem 'rack', '~>1.5.2'
+gem 'json', '~>1.6.8'
+gem 'httparty'

data/example/zoo-app/Gemfile.lock

@@ -0,0 +1,77 @@
+GEM
+  remote: https://rubygems.org/
+  remote: http://rea-rubygems/
+  specs:
+    awesome_print (1.1.0)
+    capybara (2.1.0)
+      mime-types (>= 1.16)
+      nokogiri (>= 1.3.3)
+      rack (>= 1.0.0)
+      rack-test (>= 0.5.4)
+      xpath (~> 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)
+    mime-types (1.24)
+    mini_portile (0.5.1)
+    multi_json (1.7.9)
+    multi_xml (0.5.5)
+    nokogiri (1.6.0)
+      mini_portile (~> 0.5.0)
+    pact (0.1.32)
+      awesome_print (~> 1.1.0)
+      capybara (~> 2.1.0)
+      find_a_port (~> 1.0.1)
+      hashie (~> 2.0.5)
+      json
+      rack-test (~> 0.6.2)
+      randexp (~> 0.1.7)
+      rspec (~> 2.12)
+      thin
+      thor
+    pry (0.9.12.2)
+      coderay (~> 1.0.5)
+      method_source (~> 0.8)
+      slop (~> 3.4)
+    rack (1.5.2)
+    rack-test (0.6.2)
+      rack (>= 1.0)
+    rake (10.1.0)
+    randexp (0.1.7)
+    rspec (2.14.1)
+      rspec-core (~> 2.14.0)
+      rspec-expectations (~> 2.14.0)
+      rspec-mocks (~> 2.14.0)
+    rspec-core (2.14.5)
+    rspec-expectations (2.14.2)
+      diff-lcs (>= 1.1.3, < 2.0)
+    rspec-mocks (2.14.3)
+    slop (3.4.6)
+    thin (1.5.1)
+      daemons (>= 1.0.9)
+      eventmachine (>= 0.12.6)
+      rack (>= 1.0.0)
+    thor (0.18.1)
+    xpath (2.0.0)
+      nokogiri (~> 1.3)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  bundler (~> 1.3.0)
+  httparty
+  json (~> 1.6.8)
+  pact
+  pry
+  rack (~> 1.5.2)
+  rake
+  rspec

data/example/zoo-app/lib/zoo_app/animal_service_client.rb

@@ -0,0 +1,36 @@
+require 'httparty'
+require 'zoo_app/models/alligator'
+
+module ZooApp
+  class AnimalServiceClient
+
+    include HTTParty
+    base_uri 'animal-service.com'
+
+    def self.find_alligators
+      response = get("/alligators", :headers => {'Accept' => 'application/json'})
+      if response.success?
+        parse_body(response).collect do | hash |
+          ZooApp::Animals::Alligator.new(hash)
+        end
+      else
+        raise response.body
+      end
+    end
+
+    def self.find_alligator_by_name name
+      response = get("/alligators/#{name}", :headers => {'Accept' => 'application/json'})
+      if response.success?
+        ZooApp::Animals::Alligator.new(parse_body(response))
+      elsif response.code == 404
+        nil
+      else
+        raise response.body
+      end
+    end
+
+    def self.parse_body response
+      JSON.parse(response.body, {:symbolize_names => true})
+    end
+  end
+end

data/example/zoo-app/lib/zoo_app/models/alligator.rb

@@ -0,0 +1,15 @@
+module ZooApp
+  module Animals
+    class Alligator
+      attr_reader :name
+      def initialize attributes
+        @name = attributes[:name]
+      end
+
+      def == other
+        other.is_a?(Alligator) && other.name == self.name
+      end
+
+    end
+  end
+end

data/example/zoo-app/spec/pacts/zoo_app-animal_service.json

@@ -0,0 +1,100 @@
+{
+  "producer": {
+    "name": "Animal Service"
+  },
+  "consumer": {
+    "name": "Zoo App"
+  },
+  "interactions": [
+    {
+      "description": "a request for animals",
+      "request": {
+        "method": "get",
+        "path": "/animals"
+      },
+      "response": {
+        "status": 200,
+        "headers": {
+          "Content-Type": "application/json"
+        },
+        "body": {
+          "alligators": [
+            {
+              "name": "Bob"
+            }
+          ]
+        }
+      },
+      "producer_state": "there are alligators"
+    },
+    {
+      "description": "a request for alligators",
+      "request": {
+        "method": "get",
+        "path": "/alligators",
+        "headers": {
+          "Accept": "application/json"
+        }
+      },
+      "response": {
+        "status": 200,
+        "headers": {
+          "Content-Type": "application/json"
+        },
+        "body": [
+          {
+            "name": "Bob"
+          }
+        ]
+      },
+      "producer_state": "there are alligators"
+    },
+    {
+      "description": "a request for alligator Mary",
+      "request": {
+        "method": "get",
+        "path": "/alligators/Mary",
+        "headers": {
+          "Accept": "application/json"
+        }
+      },
+      "response": {
+        "status": 200,
+        "headers": {
+          "Content-Type": "application/json"
+        },
+        "body": [
+          {
+            "name": "Mary"
+          }
+        ]
+      },
+      "producer_state": "there is an alligator named Mary"
+    },
+    {
+      "description": "a request for alligators",
+      "request": {
+        "method": "get",
+        "path": "/alligators",
+        "headers": {
+          "Accept": "application/json"
+        }
+      },
+      "response": {
+        "status": 500,
+        "headers": {
+          "Content-Type": "application/json"
+        },
+        "body": {
+          "error": "Argh!!!"
+        }
+      },
+      "producer_state": "an error has occurred"
+    }
+  ],
+  "metadata": {
+    "pact_gem": {
+      "version": "0.1.32"
+    }
+  }
+}

data/example/zoo-app/spec/service_providers/animal_service_spec.rb

@@ -0,0 +1,92 @@
+require_relative 'pact_helper'
+
+module ZooApp
+  describe "A pact with Animal Service", :pact => true do
+
+    before do
+      AnimalServiceClient.base_uri 'localhost:1234'
+    end
+
+    describe "a call to get alligators" do
+
+      context "when valid response is received" do
+        before do
+          animal_service.
+            given("there are alligators").
+              upon_receiving("a request for alligators").
+                with({ method: :get, path: '/alligators', :headers => {'Accept' => 'application/json'} }).
+                  will_respond_with({
+                    status: 200,
+                    headers: { 'Content-Type' => 'application/json' },
+                    body: [{:name => 'Bob'}]
+                  })
+        end
+
+        it "returns a list of alligators" do
+          expect(AnimalServiceClient.find_alligators).to eq [ZooApp::Animals::Alligator.new(:name => 'Bob')]
+        end
+
+      end
+
+      context "when an error response is returned" do
+        before do
+          animal_service.
+            given("an error has occurred").
+              upon_receiving("a request for alligators").
+                with({ method: :get, path: '/alligators', :headers => {'Accept' => 'application/json'} }).
+                  will_respond_with({
+                    status: 500,
+                    headers: { 'Content-Type' => 'application/json' },
+                    body: {:error => 'Argh!!!'}
+                  })
+        end
+
+        it "raises an error" do
+          expect{ AnimalServiceClient.find_alligators }.to raise_error /Argh/
+        end
+
+      end
+    end
+
+    describe "a call to get an alligator by name" do
+      context "when an alligator by the given name exists" do
+
+        before do
+          animal_service.
+            given("there is an alligator named Mary").
+              upon_receiving("a request for alligator Mary").
+                with({ method: :get, path: '/alligators/Mary', :headers => {'Accept' => 'application/json'} }).
+                  will_respond_with({
+                    status: 200,
+                    headers: { 'Content-Type' => 'application/json' },
+                    body: {:name => 'Mary'}
+                  })
+        end
+
+        it "returns the alligator" do
+          expect(AnimalServiceClient.find_alligator_by_name("Mary")).to eq ZooApp::Animals::Alligator.new(:name => 'Mary')
+        end
+
+      end
+
+      context "when an alligator by the given name does not exist" do
+
+        before do
+          animal_service.
+            given("there is an alligator named Mary").
+              upon_receiving("a request for alligator Mary").
+                with({ method: :get, path: '/alligators/Mary', :headers => {'Accept' => 'application/json'} }).
+                  will_respond_with({
+                    status: 404,
+                    headers: { 'Content-Type' => 'application/json' }
+                  })
+        end
+
+        it "returns nil" do
+          expect(AnimalServiceClient.find_alligator_by_name("Mary")).to be_nil
+        end
+
+      end
+    end
+  end
+end

data/example/zoo-app/spec/service_providers/pact_helper.rb

@@ -0,0 +1,11 @@
+require_relative '../spec_helper'
+require 'pact/consumer/rspec'
+
+Pact.service_consumer 'Zoo App' do
+  has_pact_with "Animal Service" do
+    service :animal_service do
+      port 1234
+    end
+  end
+end
+

data/example/zoo-app/spec/spec_helper.rb

@@ -0,0 +1,8 @@
+$: << File.expand_path("../../lib", __FILE__)
+
+require 'zoo_app/animal_service_client'
+
+RSpec.configure do | config |
+  config.color = true
+  config.formatter = :documentation
+end

data/lib/pact/consumer/configuration_dsl.rb

@@ -27,6 +27,8 @@ module Pact
         end
       end
 
+      alias_method :service_consumer, :consumer
+
       class ConsumerDSL
 
         def initialize &block