pact 0.1.28 → 1.3.3

data/documentation/configuration.md

@@ -0,0 +1,166 @@
+# Configuration
+
+## Menu
+
+#### Consumer and Provider configuration options
+* [diff_formatter](#diff_formatter)
+* [log_dir](#log_dir)
+* [logger](#logger)
+* [logger.level](#loggerlevel)
+
+#### Consumer only configuration options
+* [pact_dir](#pact_dir)
+* [doc_dir](#doc_dir)
+* [doc_generator](#doc_generator)
+* [pactfile_write_mode](#pactfile_write_mode)
+
+#### Provider only configuration options
+* [include](#include)
+
+## Consumer and Provider
+
+### log_dir
+
+```ruby
+Pact.configure do | config |
+  config.log_dir = './log'
+end
+```
+
+Default value: `./log`
+
+### logger
+
+```ruby
+Pact.configure do | config |
+  config.logger = Logger.new
+end
+```
+
+Default value: file logger to the configured log_dir.
+
+### logger.level
+
+```ruby
+Pact.configure do | config |
+  config.logger.level = Logger::INFO
+end
+```
+
+Default value: `Logger::DEBUG`
+
+### diff_formatter
+
+```ruby
+Pact.configure do | config |
+  config.diff_formatter = :list
+end
+```
+
+Default value: [:list](#list)
+
+Options: [:unix](#unix), [:list](#list), [:embedded](#embedded), [Custom Diff Formatter](#custom-diff-formatter)
+
+
+#### :unix
+<img src="diff_formatter_unix.png" width="700">
+
+#### :list
+
+<img src="diff_formatter_list.png" width="700">
+
+#### :embedded
+
+<img src="diff_formatter_embedded.png" width="700">
+
+
+#### Custom Diff Formatter
+
+Any object can be used that responds to `call`, accepting the argument `diff`.
+
+```ruby
+class MyCustomDiffFormatter
+
+  def self.call diff
+    ### Do stuff here
+  end
+
+end
+
+Pact.configure do | config |
+  config.diff_formatter = MyCustomDiffFormatter
+end
+```
+
+
+## Consumer
+
+### pact_dir
+
+```ruby
+Pact.configure do | config |
+  config.pact_dir = `./spec/pacts`
+end
+```
+
+Default value: `./spec/pacts`
+
+### doc_generator
+
+```ruby
+Pact.configure do | config |
+  config.doc_generator = :markdown
+end
+```
+
+Default value: none
+
+Options: [:markdown](#markdown), [Custom Doc Generator](#custom-doc-generator)
+
+#### :markdown
+
+Generates Markdown documentation based on the contents of the pact files created in this consumer. Files are created in `${Pact.configuration.doc_dir}/markdown`.
+
+#### Custom Doc Generator
+
+Any object can be used that responds to `call`, accepting the arguments `pact_dir` and `doc_dir`.
+
+```ruby
+Pact.configure do | config |
+  config.doc_generator = lambda{ | pact_dir, doc_dir | generate_some_docs(pact_dir, doc_dir) }
+end
+
+```
+
+#### doc_dir
+
+```ruby
+Pact.configure do | config |
+  config.doc_dir = './doc'
+end
+```
+
+Default value: `./doc`
+
+
+### pactfile_write_mode
+
+Default value: `:overwrite`
+Options: `:overwrite`, `:update`, `:smart`
+
+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 tedious 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.
+
+## Provider
+
+Pact uses RSpec and Rack::Test to create dynamic specs based on the pact files. RSpec configuration can be used to modify test behaviour if there is not an appropriate Pact feature. If you wish to use the same spec_helper.rb file as your unit tests, require it in the pact_helper.rb, but remember that the RSpec configurations for your unit tests may or may not be what you want for your pact verification tests.
+
+### include
+
+```ruby
+Pact.configure do | config |
+  config.include MyTestHelperMethods
+end
+```
+
+To make modules available in the provider state set_up and tear_down blocks, include them in the configuration as shown below. One common use of this to include factory methods for setting up data so that the provider states file doesn't get too bloated.
+

data/example/animal-service/Gemfile

@@ -0,0 +1,14 @@
+source 'https://rubygems.org'
+
+group :development, :test do
+  gem 'rspec'
+  gem 'pact', path: '../../'
+  gem 'pry'
+end
+
+gem 'rake'
+gem 'rack', '~>1.5.2'
+gem 'json', '~>1.6'
+gem 'sqlite3'
+gem 'sequel'
+gem 'sinatra'

data/example/animal-service/Gemfile.lock

@@ -0,0 +1,69 @@
+PATH
+  remote: ../../
+  specs:
+    pact (1.1.0.rc2)
+      awesome_print (~> 1.1)
+      find_a_port (~> 1.0.1)
+      json
+      rack-test (~> 0.6.2)
+      randexp (~> 0.1.7)
+      rspec (~> 2.12)
+      term-ansicolor (~> 1.0)
+      thor
+      webrick
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    awesome_print (1.2.0)
+    coderay (1.0.9)
+    diff-lcs (1.2.4)
+    find_a_port (1.0.1)
+    json (1.6.8)
+    method_source (0.8.2)
+    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)
+    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)
+    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)
+    sqlite3 (1.3.8)
+    term-ansicolor (1.3.0)
+      tins (~> 1.0)
+    thor (0.19.1)
+    tilt (1.4.1)
+    tins (1.1.0)
+    webrick (1.3.1)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  json (~> 1.6)
+  pact!
+  pry
+  rack (~> 1.5.2)
+  rake
+  rspec
+  sequel
+  sinatra
+  sqlite3

data/example/animal-service/Rakefile

@@ -0,0 +1,5 @@
+$: << File.join(File.dirname(__FILE__), "lib")
+
+require 'pact/tasks'
+
+task :default => 'pact:verify'

data/example/animal-service/config.ru

@@ -0,0 +1,3 @@
+require File.dirname(__FILE__) + '/lib/animal_service/api'
+
+run AnimalService::Api

data/example/animal-service/lib/animal_service/animal_repository.rb

@@ -0,0 +1,12 @@
+require 'sequel'
+require_relative 'db'
+
+module AnimalService
+  class AnimalRepository
+
+    def self.find_alligator_by_name name
+      DATABASE[:animals].where(name: name).single_record
+    end
+
+  end
+end

data/example/animal-service/lib/animal_service/api.rb

@@ -0,0 +1,28 @@
+require 'sinatra/base'
+require_relative 'animal_repository'
+
+module AnimalService
+
+  class Api < Sinatra::Base
+
+    set :raise_errors, false
+    set :show_exceptions, false
+
+    error do
+      e = env['sinatra.error']
+      content_type :json
+      status 500
+      {error: e.message, backtrace: e.backtrace}.to_json
+    end
+
+    get '/alligators/:name' do
+      if (alligator = AnimalRepository.find_alligator_by_name(params[:name]))
+        content_type :json
+        alligator.to_json
+      else
+        status 404
+      end
+    end
+
+  end
+end

data/example/animal-service/lib/animal_service/db.rb

@@ -0,0 +1,5 @@
+require 'sequel'
+
+module AnimalService
+  DATABASE ||= Sequel.connect(adapter: 'sqlite', database: './db/animal_db.sqlite3')
+end

data/example/animal-service/spec/service_consumers/pact_helper.rb

@@ -0,0 +1,11 @@
+require 'pact/provider/rspec'
+
+require "./spec/service_consumers/provider_states_for_zoo_app"
+
+Pact.service_provider 'Animal Service' do
+
+  honours_pact_with "Zoo App" do
+    pact_uri '../zoo-app/spec/pacts/zoo_app-animal_service.json'
+  end
+
+end

data/example/animal-service/spec/service_consumers/provider_states_for_zoo_app.rb

@@ -0,0 +1,26 @@
+require 'sequel'
+require 'animal_service/db'
+require 'animal_service/animal_repository'
+
+Pact.provider_states_for "Zoo App" do
+
+  set_up do
+    AnimalService::DATABASE[:animals].truncate
+  end
+
+  provider_state "there is an alligator named Mary" do
+    set_up do
+      AnimalService::DATABASE[:animals].insert(name: 'Mary')
+    end
+  end
+
+  provider_state "there is not an alligator named Mary" do
+    no_op
+  end
+
+  provider_state "an error occurs retrieving an alligator" do
+    set_up do
+      allow(AnimalService::AnimalRepository).to receive(:find_alligator_by_name).and_raise("Argh!!!")
+    end
+  end
+end

data/example/zoo-app/Gemfile

@@ -0,0 +1,12 @@
+source 'https://rubygems.org'
+
+group :development, :test do
+  gem 'rspec'
+  gem 'pact', path: '../../'
+  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,63 @@
+PATH
+  remote: ../../
+  specs:
+    pact (1.1.0.rc3)
+      awesome_print (~> 1.1)
+      find_a_port (~> 1.0.1)
+      json
+      rack-test (~> 0.6.2)
+      randexp (~> 0.1.7)
+      rspec (~> 2.12)
+      term-ansicolor (~> 1.0)
+      thor
+      webrick
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    awesome_print (1.2.0)
+    coderay (1.0.9)
+    diff-lcs (1.2.4)
+    find_a_port (1.0.1)
+    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.7.9)
+    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-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)
+    term-ansicolor (1.3.0)
+      tins (~> 1.0)
+    thor (0.19.1)
+    tins (1.1.0)
+    webrick (1.3.1)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  httparty
+  json (~> 1.6.8)
+  pact!
+  pry
+  rack (~> 1.5.2)
+  rake
+  rspec

data/example/zoo-app/Rakefile

@@ -0,0 +1,5 @@
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/example/zoo-app/doc/pacts/markdown/README.md

@@ -0,0 +1,3 @@
+### Pacts for Zoo App
+
+* [Animal Service](Zoo App - Animal Service.md)

data/example/zoo-app/doc/pacts/markdown/Zoo App - Animal Service.md

@@ -0,0 +1,75 @@
+### A pact between Zoo App and Animal Service
+
+#### Requests from Zoo App to Animal Service
+
+* [A request for an alligator](#a_request_for_an_alligator_given_there_is_an_alligator_named_Mary) given there is an alligator named Mary
+
+* [A request for an alligator](#a_request_for_an_alligator_given_there_is_not_an_alligator_named_Mary) given there is not an alligator named Mary
+
+* [A request for an alligator](#a_request_for_an_alligator_given_an_error_occurs_retrieving_an_alligator) given an error occurs retrieving an alligator
+
+#### Interactions
+
+<a name="a_request_for_an_alligator_given_there_is_an_alligator_named_Mary"></a>
+Given **there is an alligator named Mary**, upon receiving **a request for an alligator** from Zoo App, with
+```json
+{
+  "method": "get",
+  "path": "/alligators/Mary",
+  "headers": {
+    "Accept": "application/json"
+  }
+}
+```
+Animal Service will respond with:
+```json
+{
+  "status": 200,
+  "headers": {
+    "Content-Type": "application/json;charset=utf-8"
+  },
+  "body": {
+    "name": "Mary"
+  }
+}
+```
+<a name="a_request_for_an_alligator_given_there_is_not_an_alligator_named_Mary"></a>
+Given **there is not an alligator named Mary**, upon receiving **a request for an alligator** from Zoo App, with
+```json
+{
+  "method": "get",
+  "path": "/alligators/Mary",
+  "headers": {
+    "Accept": "application/json"
+  }
+}
+```
+Animal Service will respond with:
+```json
+{
+  "status": 404
+}
+```
+<a name="a_request_for_an_alligator_given_an_error_occurs_retrieving_an_alligator"></a>
+Given **an error occurs retrieving an alligator**, upon receiving **a request for an alligator** from Zoo App, with
+```json
+{
+  "method": "get",
+  "path": "/alligators/Mary",
+  "headers": {
+    "Accept": "application/json"
+  }
+}
+```
+Animal Service will respond with:
+```json
+{
+  "status": 500,
+  "headers": {
+    "Content-Type": "application/json;charset=utf-8"
+  },
+  "body": {
+    "error": "Argh!!!"
+  }
+}
+```

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

@@ -0,0 +1,40 @@
+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'})
+      handle_response response do
+        parse_body(response).collect do | hash |
+          ZooApp::Animals::Alligator.new(hash)
+        end
+      end
+    end
+
+    def self.find_alligator_by_name name
+      response = get("/alligators/#{name}", :headers => {'Accept' => 'application/json'})
+      when_successful(response) do
+        ZooApp::Animals::Alligator.new(parse_body(response))
+      end
+    end
+
+    def self.when_successful response
+      if response.success?
+        yield
+      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,67 @@
+{
+  "provider": {
+    "name": "Animal Service"
+  },
+  "consumer": {
+    "name": "Zoo App"
+  },
+  "interactions": [
+    {
+      "description": "a request for an alligator",
+      "provider_state": "there is an alligator named Mary",
+      "request": {
+        "method": "get",
+        "path": "/alligators/Mary",
+        "headers": {
+          "Accept": "application/json"
+        }
+      },
+      "response": {
+        "status": 200,
+        "headers": {
+          "Content-Type": "application/json;charset=utf-8"
+        },
+        "body": {
+          "name": "Mary"
+        }
+      }
+    },
+    {
+      "description": "a request for an alligator",
+      "provider_state": "there is not an alligator named Mary",
+      "request": {
+        "method": "get",
+        "path": "/alligators/Mary",
+        "headers": {
+          "Accept": "application/json"
+        }
+      },
+      "response": {
+        "status": 404
+      }
+    },
+    {
+      "description": "a request for an alligator",
+      "provider_state": "an error occurs retrieving an alligator",
+      "request": {
+        "method": "get",
+        "path": "/alligators/Mary",
+        "headers": {
+          "Accept": "application/json"
+        }
+      },
+      "response": {
+        "status": 500,
+        "headers": {
+          "Content-Type": "application/json;charset=utf-8"
+        },
+        "body": {
+          "error": "Argh!!!"
+        }
+      }
+    }
+  ],
+  "metadata": {
+    "pactSpecificationVersion": "1.0.0"
+  }
+}