pacto 0.3.0.pre → 0.3.0

data/Rakefile

@@ -5,17 +5,17 @@ require 'cucumber'
 require 'cucumber/rake/task'
 require 'coveralls/rake/task'
 require 'rubocop/rake_task'
+require 'rake/notes/rake_task'
 
 Coveralls::RakeTask.new
 
 Rubocop::RakeTask.new(:rubocop) do |task|
-  task.patterns = ['**/*.rb', 'Rakefile']
   # abort rake on failure
-  task.fail_on_error = false
+  task.fail_on_error = true
 end
 
 Cucumber::Rake::Task.new(:journeys) do |t|
-  t.cucumber_opts = 'features --format pretty'
+  t.cucumber_opts = 'features --format progress'
 end
 
 RSpec::Core::RakeTask.new(:unit) do |t|

data/features/configuration/strict_matchers.feature

@@ -0,0 +1,97 @@
+Feature: Strict Matching
+
+  By default, Pacto matches requests to contracts (and stubs) using exact request paths, parameters, and headers.  This strict behavior is useful for Consumer-Driven Contracts.
+
+  You can use less strict matching so the same contract can match multiple similar requests.  This is useful for matching contracts with resource identifiers in the path.  Any placeholder in the path (like :id in /beers/:id) is considered a resource identifier and will match any alphanumeric combination.
+
+  You can change the default behavior to the behavior that allows placeholders and ignores headers or request parameters by setting the strict_matchers configuration option:
+
+  ```ruby
+    Pacto.configure do |config|
+      config.strict_matchers = false
+    end
+  ```
+
+  Background:
+    Given a file named "contracts/hello_contract.json" with:
+      """json
+      {
+        "request": {
+          "method": "GET",
+          "path": "/hello/:id",
+          "headers": {
+            "Accept": "application/json"
+          },
+          "params": {}
+        },
+
+        "response": {
+          "status": 200,
+          "headers": { "Content-Type": "application/json" },
+          "body": {
+            "type": "object",
+            "required": true,
+            "properties": {
+              "message": { "type": "string", "required": true, "default": "Hello, world!" }
+            }
+          }
+        }
+      }
+      """
+
+    Given a file named "requests.rb" with:
+      """ruby
+      require 'pacto'
+
+      strict = ARGV[0] == "true"
+      puts "Pacto.configuration.strict_matchers = #{strict}"
+      puts
+
+      Pacto.configure do |config|
+        config.strict_matchers = strict
+      end
+      Pacto.load_contracts('contracts', 'http://dummyprovider.com').stub_all
+
+      def response url, headers
+        begin
+          response = Faraday.get(url) do |req|
+            req.headers = headers[:headers]
+          end
+          response.body
+        rescue WebMock::NetConnectNotAllowedError => e
+          e.class
+        end
+      end
+
+      print 'Exact: '
+      puts response 'http://dummyprovider.com/hello/:id', headers: {'Accept' => 'application/json' }
+
+      print 'Wrong headers: '
+      puts response 'http://dummyprovider.com/hello/:id', headers: {'Content-Type' => 'application/json' }
+
+      print 'ID placeholder: '
+      puts response 'http://dummyprovider.com/hello/123', headers: {'Accept' => 'application/json' }
+      """
+
+  Scenario: Default (strict) behavior
+    When I run `bundle exec ruby requests.rb true`
+    Then the output should contain:
+      """
+      Pacto.configuration.strict_matchers = true
+
+      Exact: {"message":"Hello, world!"}
+      Wrong headers: WebMock::NetConnectNotAllowedError
+      ID placeholder: WebMock::NetConnectNotAllowedError
+
+      """
+
+  Scenario: Non-strict matching
+    When I run `bundle exec ruby requests.rb false`
+    Then the output should contain:
+      """
+      Pacto.configuration.strict_matchers = false
+
+      Exact: {"message":"Hello, world!"}
+      Wrong headers: {"message":"Hello, world!"}
+      ID placeholder: {"message":"Hello, world!"}
+      """    

data/features/evolve/README.md

@@ -0,0 +1,11 @@
+## Consumer-Driven Contract Recommendations
+
+If you are using Pacto for Consumer-Driven Contracts, we recommend avoiding the advanced features so you'll test with the strictest Contract possible.  We recommend:
+
+- Do not use templating, let Pacto use the json-generator
+- Use strict request matching
+- Use multiple contracts for the same service to capture attributes that are required in some situations but not others
+
+The host address is intentionally left out of the request specification so that we can validate a contract against any provider.
+It also reinforces the fact that a contract defines the expectation of a consumer, and not the implementation of any specific provider.
+

data/features/evolve/existing_services.feature

@@ -0,0 +1,82 @@
+Feature: Existing services journey
+
+  Scenario: Generating the contracts
+    Given I have a Rakefile
+    Given an existing set of services
+    When I execute:
+    """ruby
+    require 'pacto'
+
+    Pacto.configure do | c |
+      c.contracts_path = 'contracts'
+    end
+
+    Pacto.generate!
+
+    Faraday.get 'http://www.example.com/service1'
+    Faraday.get 'http://www.example.com/service2'
+    """
+    Then the following files should exist:
+    | contracts/www.example.com/service1.json |
+    | contracts/www.example.com/service2.json |
+
+  @no-clobber
+  Scenario: Ensuring all contracts are valid
+    When I successfully run `bundle exec rake pacto:meta_validate['contracts']`
+    Then the output should contain exactly:
+    """
+    Validating contracts/www.example.com/service1.json
+    Validating contracts/www.example.com/service2.json
+    All contracts successfully meta-validated
+
+    """
+
+  @no-clobber
+  Scenario: Stubbing with the contracts
+    Given a file named "test.rb" with:
+    """ruby
+    require 'pacto'
+
+    Pacto.configure do | c |
+      c.contracts_path = 'contracts'
+    end
+
+    contracts = Pacto.load_contracts('contracts/www.example.com/', 'http://www.example.com')
+    contracts.stub_all
+
+    puts Faraday.get('http://www.example.com/service1').body
+    puts Faraday.get('http://www.example.com/service2').body
+    """
+    When I successfully run `bundle exec ruby test.rb`
+    Then the output should contain exactly:
+    """
+    {"thoughtworks":"bar"}
+    {"service2":["bar"]}
+
+    """
+
+  @no-clobber
+  Scenario: Expecting a change
+    When I make replacements in "contracts/www.example.com/service1.json":
+    | pattern | replacement |
+    | string  | integer     |
+    When I execute:
+    """ruby
+    require 'pacto'
+
+    Pacto.stop_generating!
+
+    Pacto.configure do | c |
+      c.contracts_path = 'contracts'
+    end
+
+    Pacto.load_contracts('contracts', 'http://www.example.com').stub_all
+    Pacto.validate!
+
+    Faraday.get 'http://www.example.com/service1'
+    Faraday.get 'http://www.example.com/service2'
+    """
+    Then the output should contain exactly:
+    """
+    
+    """

data/features/generate/README.md

@@ -0,0 +1,5 @@
+We know - json-schema can get pretty verbose!  It's a powerful tool, but writing the entire Contract by hand for a complex service is a painstaking task.  We've created a simple generator to speed this process up.  You can invoke it programmatically, or with the provided rake task.
+
+The basic generate we've bundled with Pacto completes partially defined Contracts - Contracts that have a request defined but no response.  We haven't bundled any other generates, but you could use the API to generate from other sources, like existing [VCR](https://github.com/vcr/vcr) cassettes, [apiblueprint](http://apiblueprint.org/), or [WADL](https://wadl.java.net/).  If you want some help or ideas, try the [pacto mailing-list](https://groups.google.com/forum/#!forum/pacto-gem).
+
+Note: Request headers are only recorded if they are in the response's [Vary header](http://www.subbu.org/blog/2007/12/vary-header-for-restful-applications), so make sure your services return a proper Vary for best results!

data/features/generate/generation.feature

@@ -0,0 +1,28 @@
+@needs_server
+Feature: Contract Generation
+
+  We know - json-schema can get pretty verbose!  It's a powerful tool, but writing the entire Contract by hand for a complex service is a painstaking task.  We've created a simple generator to speed this process up.  You can invoke it programmatically, or with the provided rake task.
+
+  You just need to create a partial Contract that only describes the request.  The generator will then execute the request, and use the response to generate a full Contract.
+
+  Remember, we only record request headers if they are in the response's [Vary header](http://www.subbu.org/blog/2007/12/vary-header-for-restful-applications), so make sure your services return a proper Vary for best results!
+
+  Background:
+    Given a file named "requests/my_contract.json" with:
+    """
+        {
+        "request": {
+          "method": "GET",
+          "path": "/hello",
+          "headers": {
+            "Accept": "application/json"
+          }
+        },
+        "response": {
+          "status": 200,
+          "body": {
+            "required": true
+          }
+        }
+      }
+    """

data/features/steps/pacto_steps.rb

@@ -0,0 +1,75 @@
+Given(/^Pacto is configured with:$/) do |string|
+  steps %Q{
+    Given a file named "pacto_config.rb" with:
+    """ruby
+    #{string}
+    """
+  }
+end
+
+Given(/^I have a Rakefile$/) do
+  steps %Q{
+    Given a file named "Rakefile" with:
+    """ruby
+    require 'pacto/rake_task'
+    """
+  }
+end
+
+When(/^I request "(.*?)"$/) do |url|
+  steps %Q{
+    Given a file named "request.rb" with:
+    """ruby
+    require 'pacto'
+    require_relative 'pacto_config'
+    require 'faraday'
+
+    resp = Faraday.get('#{url}') do |req|
+      req.headers = { 'Accept' => 'application/json' }
+    end
+    puts resp.body
+    """
+    When I run `bundle exec ruby request.rb`
+  }
+end
+
+Given(/^an existing set of services$/) do
+  WebMock.stub_request(:get, 'www.example.com/service1').to_return(:body => {'thoughtworks' => 'pacto' }.to_json)
+  WebMock.stub_request(:post, 'www.example.com/service1').with(:body => 'thoughtworks').to_return(:body => 'pacto')
+  WebMock.stub_request(:get, 'www.example.com/service2').to_return(:body => {'service2' => %w{'thoughtworks', 'pacto'} }.to_json)
+  WebMock.stub_request(:post, 'www.example.com/service2').with(:body => 'thoughtworks').to_return(:body => 'pacto')
+end
+
+When(/^I execute:$/) do |script|
+  FileUtils.mkdir_p 'tmp/aruba'
+  Dir.chdir 'tmp/aruba' do
+    begin
+      script = <<-eof
+      require 'stringio'
+      begin $stdout = StringIO.new
+        #{ script }
+        $stdout.string
+      ensure
+        $stdout = STDOUT
+      end
+eof
+      eval(script) # rubocop:disable Eval
+                   # It's just for testing...
+
+    rescue SyntaxError => e
+      puts e
+      puts e.backtrace
+    end
+  end
+end
+
+When(/^I make replacements in "([^"]*)":$/) do |file_name, replacements|
+  Dir.chdir 'tmp/aruba' do
+    content = File.read file_name
+    replacements.rows.each do | pattern, replacement |
+      content.gsub! Regexp.new(pattern), replacement
+    end
+
+    File.open(file_name, 'w') { |file| file.write content }
+  end
+end

data/features/stub/README.md

@@ -0,0 +1,2 @@
+You can write your own stubs and use Pacto to [validate](https://www.relishapp.com/maxlinc/pacto/docs/validate) them, or you can just let Pacto create stubs for you.
+

data/features/stub/templates.feature

@@ -0,0 +1,46 @@
+Feature: Templating
+
+  If you want to create more dynamic stubs, you can use Pacto templating.  Currently the only supported templating mechanism is to use ERB in the "default" attributes of the json-schema.
+
+  Background:
+    Given Pacto is configured with:
+      """ruby
+      Pacto.configure do |c|
+        c.register_hook Pacto::Hooks::ERBHook.new
+      end
+      Pacto.load_contracts('contracts', 'http://example.com').stub_all
+      """
+    Given a file named "contracts/template.json" with:
+      """json
+      {
+        "request": {
+          "method": "GET",
+          "path": "/hello",
+          "headers": {
+            "Accept": "application/json"
+          },
+          "params": {}
+        },
+
+        "response": {
+          "status": 200,
+          "headers": { "Content-Type": "application/json" },
+          "body": {
+            "type": "object",
+            "required": true,
+            "properties": {
+              "message": { "type": "string", "required": true,
+                "default": "<%= 'Hello, world!'.reverse %>"
+              }
+            }
+          }
+        }
+      }
+      """
+
+  Scenario: ERB Template
+    When I request "http://example.com/hello"
+    Then the output should contain:
+      """
+      {"message":"!dlrow ,olleH"}
+      """

data/features/support/env.rb

@@ -1,16 +1,22 @@
 require_relative '../../spec/coveralls_helper'
 require 'rake'
+require 'webmock'
 require 'aruba'
 require 'aruba/cucumber'
-require 'aruba/in_process'
 require 'aruba/jruby' if RUBY_PLATFORM == 'java'
-require 'pacto/server'
+require_relative '../../spec/pacto/server'
 
 Before do
+  # Given I successfully run `bundle install` can take a while.
   @aruba_timeout_seconds = RUBY_PLATFORM == 'java' ? 60 : 10
 end
 
-Before('@needs_server') do
-  @server = Pacto::Server::Dummy.new 8000, '/hello', '{"message": "Hello World!"}'
-  @server.start
+# Was only going to use for @needs_server, but its easier to leave it running
+@server = Pacto::Server::Dummy.new 8000, '/hello', '{"message": "Hello World!"}'
+@server.start
+
+Around do | scenario, block |
+  Bundler.with_clean_env do
+    block.call
+  end
 end

data/features/validate/README.md

@@ -0,0 +1 @@
+You can use Pacto to do Integration Contract Testing - making sure your service and any test double that simulates the service are similar.  If you generate your Contracts from documentation, you can be fairly confident that all three - live services, test doubles, and documentation - are in sync.

data/features/validate/body_only.feature

@@ -0,0 +1,85 @@
+Feature: Validation
+
+  You can validate just the body of the contract. This may be useful if you want to validate a stubbing system that does not stub the fully connection, or if Pacto is currently unable to validate your headers.
+
+  Background:
+    Given a file named "Gemfile" with:
+    """ruby
+    source 'https://rubygems.org'
+
+    gem 'pacto', :path => '../..'
+    gem 'excon'
+    """
+    Given a file named "validate.rb" with:
+      """ruby
+      require 'pacto'
+      require_relative 'my_service'
+
+      contract_list = Pacto.load_contracts('contracts', 'http://example.com')
+      contract_list.stub_all
+
+      contract = contract_list.contracts.first
+      service = MyService.new
+      response = service.hello
+      successful = contract.validate_consumer nil, response, :body_only => true
+      puts "Validated successfully!" if successful
+      """
+    Given a file named "contracts/template.json" with:
+      """json
+      {
+        "request": {
+          "method": "GET",
+          "path": "/hello",
+          "headers": {
+            "Accept": "application/json"
+          },
+          "params": {}
+        },
+
+        "response": {
+          "status": 200,
+          "headers": { "Content-Type": "application/json" },
+          "body": {
+            "type": "object",
+            "required": true,
+            "properties": {
+              "message": { "type": "string", "required": true
+              }
+            }
+          }
+        }
+      }
+      """
+
+  Scenario: Validate the response body only
+    # This should be in the Before block, but https://github.com/cucumber/cucumber/issues/52
+    Given I successfully run `bundle install --local`
+    Given a file named "my_service.rb" with:
+    """ruby
+    require 'excon'
+    class MyService
+      def response(params={})
+        body    = params[:body] || {}
+        status  = params[:status] || 200
+        headers = params[:headers] || {}
+
+        response = Excon::Response.new(:body => body, :headers => headers, :status => status)
+        if params.has_key?(:expects) && ![*params[:expects]].include?(response.status)
+          raise(Excon::Errors.status_error(params, response))
+        else response
+        end
+      end
+
+      def hello
+        body = {
+          'message' => 'Hi!'
+        }
+        response({:body => body})
+      end
+    end
+    """
+    When I run `bundle exec ruby validate.rb`
+    Then the output should contain:
+      """
+      Validated successfully!
+      """