mustwin-vcr 2.9.3

data/features/configuration/query_parser.feature

@@ -0,0 +1,84 @@
+Feature: query_parser
+
+  By default, VCR will parse query strings using `CGI.parse` from the Ruby
+  standard library. This may not be the most optimal or performant library
+  available.  You can set the `query_parser` configuration option to use a
+  different parser (such as `Rack::Utils.method(:parse_query)`) to decode,
+  normalize, and/or provide a comparison object for query strings.
+
+  The configured query parser needs to expose a `.call` method that returns an
+  object which is comparable. This instance needs to implement the following
+  API:
+
+    * `#==`     => boolean
+
+  Background:
+    Given a file named "cassettes/example.yml" with:
+      """
+      ---
+      http_interactions:
+      - request:
+          method: get
+          uri: http://url.example.com/?bravo=2&alpha=1
+          body:
+            encoding: UTF-8
+            string: ""
+          headers: {}
+        response:
+          status:
+            code: 200
+            message: OK
+          headers:
+            Content-Length:
+            - "5"
+          body:
+            encoding: UTF-8
+            string: Hello
+          http_version: "1.1"
+        recorded_at: Tue, 25 Sep 2012 04:58:44 GMT
+      recorded_with: VCR 2.2.5
+      """
+
+  Scenario: the VCR query parser gets its value from `query_parser`
+    Given a file named "query_parser.rb" with:
+      """ruby
+      require 'vcr'
+      require 'rack'
+
+      VCR.configure do |c|
+        c.query_parser = lambda { |query| raise query.inspect }
+        c.default_cassette_options = {:match_requests_on => [:query]}
+        c.hook_into :webmock
+        c.cassette_library_dir = 'cassettes'
+      end
+
+      uri = URI.parse('http://other-url.example.com/?bravo=2&alpha=1')
+      VCR.use_cassette('example') do
+        puts Net::HTTP.get_response(uri).body
+      end
+      """
+     When I run `ruby query_parser.rb`
+     Then it should fail with an error like:
+     """
+     "alpha=1&bravo=2"
+     """
+
+
+  Scenario: the `query_parser` defaults to the standard library's `CGI.parse`
+    Given a file named "query_parser_default.rb" with:
+      """ruby
+      require 'vcr'
+
+      VCR.configure do |c|
+        c.hook_into :webmock
+        c.default_cassette_options = {:match_requests_on => [:query]}
+        c.cassette_library_dir = 'cassettes'
+      end
+
+      uri = URI.parse('http://other-url.example.com/?bravo=2&alpha=1')
+      VCR.use_cassette('example') do
+        puts Net::HTTP.get_response(uri).body
+      end
+      """
+     When I run `ruby query_parser_default.rb`
+     Then it should pass with "Hello"

data/features/configuration/uri_parser.feature

@@ -0,0 +1,89 @@
+Feature: uri_parser
+
+  By default, VCR will parse URIs using `URI` from the Ruby standard
+  library. There are some URIs seen out in the wild that `URI` cannot
+  parse properly. You can set the `uri_parser` configuration option
+  to use a different parser (such as `Addressable::URI`) to work with
+  these URIs.
+
+  The configured URI parser needs to expose a `.parse` class method
+  that returns an instance of the uri. This uri instance needs to
+  implement the following API:
+
+    * `#scheme` => a string
+    * `#host`   => a string
+    * `#port`   => a fixnum
+    * `#path`   => a string
+    * `#query`  => a string
+    * `#to_s`   => a string
+    * `#port=`
+    * `#query=`
+    * `#==`     => boolean
+
+  Background:
+    Given a file named "cassettes/example.yml" with:
+      """
+      ---
+      http_interactions:
+      - request:
+          method: get
+          uri: http://bad_url.example.com/
+          body:
+            encoding: UTF-8
+            string: ""
+          headers: {}
+        response:
+          status:
+            code: 200
+            message: OK
+          headers:
+            Content-Length:
+            - "5"
+          body:
+            encoding: UTF-8
+            string: Hello
+          http_version: "1.1"
+        recorded_at: Tue, 25 Sep 2012 04:58:44 GMT
+      recorded_with: VCR 2.2.5
+      """
+
+  Scenario: the VCR uri parser gets its value from `uri_parser`
+    Given a file named "uri_parser.rb" with:
+      """ruby
+      require 'vcr'
+      require 'addressable/uri'
+
+      VCR.configure do |c|
+        c.uri_parser = Addressable::URI
+        c.hook_into :webmock
+        c.cassette_library_dir = 'cassettes'
+      end
+
+      VCR.use_cassette('example') do
+        puts Net::HTTP.get_response('bad_url.example.com', '/').body
+      end
+      """
+     When I run `ruby uri_parser.rb`
+     Then it should pass with "Hello"
+
+  Scenario: the `uri_parser` defaults to the standard library's `URI`
+    Given a file named "uri_parser_default.rb" with:
+      """ruby
+      require 'vcr'
+      require 'addressable/uri'
+
+      VCR.configure do |c|
+        c.hook_into :webmock
+        c.cassette_library_dir = 'cassettes'
+      end
+
+      VCR.use_cassette('example') do
+        puts Net::HTTP.get_response('bad_url.example.com', '/').body
+      end
+      """
+     When I run `ruby uri_parser_default.rb`
+     Then it should fail with an error like:
+     """
+     URI::InvalidURIError
+     """
+

data/features/getting_started.md

@@ -0,0 +1,82 @@
+### Install it
+
+    [sudo] gem install vcr
+    [sudo] gem install webmock
+
+### Configure it
+
+Create a file named `vcr_setup.rb` with content like:
+
+    require 'vcr'
+
+    VCR.configure do |c|
+      c.cassette_library_dir = 'vcr_cassettes'
+      c.hook_into :webmock
+    end
+
+Ensure this file is required by your test suite before any
+of the tests are run.
+
+### Use it
+
+Run your tests.  Any tests that make HTTP requests using Net::HTTP will
+raise errors like:
+
+    ================================================================================
+    An HTTP request has been made that VCR does not know how to handle:
+      GET http://example.com/
+
+    There is currently no cassette in use. There are a few ways
+    you can configure VCR to handle this request:
+
+      * If you want VCR to record this request and play it back during future test
+        runs, you should wrap your test (or this portion of your test) in a
+        `VCR.use_cassette` block [1].
+      * If you only want VCR to handle requests made while a cassette is in use,
+        configure `allow_http_connections_when_no_cassette = true`. VCR will
+        ignore this request since it is made when there is no cassette [2].
+      * If you want VCR to ignore this request (and others like it), you can
+        set an `ignore_request` callback [3].
+
+    [1] https://www.relishapp.com/myronmarston/vcr/v/2-0-0/docs/getting-started
+    [2] https://www.relishapp.com/myronmarston/vcr/v/2-0-0/docs/configuration/allow-http-connections-when-no-cassette
+    [3] https://www.relishapp.com/myronmarston/vcr/v/2-0-0/docs/configuration/ignore-request
+    ================================================================================
+
+Find one of these tests (preferably one that uses the same HTTP method and
+request URL every time--if not, you'll have to configure the request matcher).
+Wrap the body of it (or at least the code that makes the HTTP request) in a
+`VCR.use_cassette` block:
+
+    VCR.use_cassette('whatever cassette name you want') do
+       # the body of the test would go here...
+    end
+
+Run this test.  It will record the HTTP request to disk as a cassette (a
+test fixture), with content like:
+
+    ---
+    http_interactions:
+    - request:
+        method: get
+        uri: http://example.com/
+        body: ''
+        headers: {}
+      response:
+        status:
+          code: 200
+          message: OK
+        headers:
+          Content-Type:
+          - text/html;charset=utf-8
+          Content-Length:
+          - '26'
+        body: This is the response body
+        http_version: '1.1'
+      recorded_at: Tue, 01 Nov 2011 04:58:44 GMT
+    recorded_with: VCR 2.0.0
+
+Disconnect your computer from the internet.  Run the test again.
+It should pass since VCR is automatically replaying the recorded
+response when the request is made.
+

data/features/hooks/after_http_request.feature

@@ -0,0 +1,58 @@
+Feature: after_http_request hook
+
+  The `after_http_request` hook gets called with each request and response
+  just after a request has completed. It can be used for many things:
+
+    * globally logging requests and responses
+    * ejecting the current cassette (i.e. if you inserted it in a
+      `before_http_request` hook)
+
+  You can also pass one or more "filters" to `after_http_request`, to make
+  the hook only be called for some requests. Any object that responds to `#to_proc`
+  can be a filter.  Here are some simple examples:
+
+    * `:real?` -- only real requests
+    * `:stubbed?` -- only stubbed requests
+    * `:ignored?` -- only ignored requests
+    * `:recordable?` -- only requests that are being recorded
+    * `lambda { |req| URI(req.uri).host == 'amazon.com' }` -- only requests to amazon.com.
+
+  Scenario Outline: log all requests and responses using after_http_request hook
+    Given a file named "after_http_request.rb" with:
+      """ruby
+      include_http_adapter_for("<http_lib>")
+
+      $server = start_sinatra_app do
+        get('/foo') { "Hello World (foo)" }
+        get('/bar') { "Hello World (bar)" }
+      end
+
+      require 'vcr'
+
+      VCR.configure do |c|
+        <configuration>
+        c.cassette_library_dir = 'cassettes'
+        c.ignore_localhost = true
+        c.after_http_request(:ignored?, lambda { |req| req.uri =~ /foo/ }) do |request, response|
+          uri = request.uri.sub(/:\d+/, ":7777")
+          puts "Response for #{request.method} #{uri}: #{response.body}"
+        end
+      end
+
+      make_http_request(:get, "http://localhost:#{$server.port}/foo")
+      make_http_request(:get, "http://localhost:#{$server.port}/bar")
+      """
+    When I run `ruby after_http_request.rb`
+    Then the output should contain "Response for get http://localhost:7777/foo: Hello World (foo)"
+     But the output should not contain "bar"
+
+   Examples:
+      | configuration         | http_lib              |
+      | c.hook_into :fakeweb  | net/http              |
+      | c.hook_into :webmock  | net/http              |
+      | c.hook_into :webmock  | httpclient            |
+      | c.hook_into :webmock  | curb                  |
+      | c.hook_into :typhoeus | typhoeus              |
+      | c.hook_into :excon    | excon                 |
+      | c.hook_into :faraday  | faraday (w/ net_http) |
+

data/features/hooks/around_http_request.feature

@@ -0,0 +1,57 @@
+@exclude-18 @exclude-1.9.3p327
+Feature: around_http_request hook
+
+  The `around_http_request` hook wraps each HTTP request. It can be used
+  rather than separate `before_http_request` and `after_http_request` hooks
+  to simplify wrapping/transactional logic (such as using a VCR cassette).
+
+  In your block, call `#proceed` on the yielded request to cause it to continue.
+  Alternately, you can treat the request as a proc and pass it on to a method that
+  expects a block by prefixing it with an ampersand (`&request`).
+
+  Note that `around_http_request` will not work on Ruby 1.8.  It uses a fiber
+  under the covers and thus is only available on interpreters that support fibers.
+  On 1.8, you can use separate `before_http_request` and `after_http_request` hooks.
+
+  Scenario Outline: globally handle requests using an around_http_request hook
+    Given a file named "globally_handle_requests.rb" with:
+      """ruby
+      include_http_adapter_for("<http_lib>")
+
+      request_count = 0
+      $server = start_sinatra_app do
+        get('/') { "Response #{request_count += 1 }" }
+      end
+
+      require 'vcr'
+
+      VCR.configure do |c|
+        <configuration>
+        c.cassette_library_dir = 'cassettes'
+        c.default_cassette_options = { :serialize_with => :syck }
+        c.around_http_request do |request|
+          VCR.use_cassette('global', :record => :new_episodes, &request)
+        end
+      end
+
+      puts "Response for request 1: " + response_body_for(:get, "http://localhost:#{$server.port}/")
+      puts "Response for request 2: " + response_body_for(:get, "http://localhost:#{$server.port}/")
+      """
+    When I run `ruby globally_handle_requests.rb`
+    Then it should pass with:
+      """
+      Response for request 1: Response 1
+      Response for request 2: Response 1
+      """
+    And the file "cassettes/global.yml" should contain "Response 1"
+
+   Examples:
+      | configuration         | http_lib              |
+      | c.hook_into :fakeweb  | net/http              |
+      | c.hook_into :webmock  | net/http              |
+      | c.hook_into :webmock  | httpclient            |
+      | c.hook_into :webmock  | curb                  |
+      | c.hook_into :typhoeus | typhoeus              |
+      | c.hook_into :excon    | excon                 |
+      | c.hook_into :faraday  | faraday (w/ net_http) |
+

data/features/hooks/before_http_request.feature

@@ -0,0 +1,63 @@
+Feature: before_http_request hook
+
+  The `before_http_request` hook gets called with each request
+  just before it proceeds. It can be used for many things:
+
+    * globally logging requests
+    * inserting a particular cassette based on the request URI host
+    * raising a timeout error
+
+  You can also pass one or more "filters" to `before_http_request`, to make
+  the hook only be called for some requests. Any object that responds to `#to_proc`
+  can be a filter.  Here are some simple examples:
+
+    * `:real?` -- only real requests
+    * `:stubbed?` -- only stubbed requests
+    * `:ignored?` -- only ignored requests
+    * `:recordable?` -- only requests that are being recorded
+    * `lambda { |r| URI(r.uri).host == 'amazon.com' }` -- only requests to amazon.com.
+
+  Scenario Outline: log all requests using a before_http_request hook
+    Given a file named "before_http_request.rb" with:
+      """ruby
+      include_http_adapter_for("<http_lib>")
+
+      if ARGV.include?('--with-server')
+        $server = start_sinatra_app do
+          get('/') { "Hello World" }
+        end
+      end
+
+      require 'vcr'
+
+      VCR.configure do |c|
+        <configuration>
+        c.cassette_library_dir = 'cassettes'
+        c.before_http_request(:real?) do |request|
+          File.open(ARGV.first, 'w') do |f|
+            f.write("before real request: #{request.method} #{request.uri}")
+          end
+        end
+      end
+
+      VCR.use_cassette('hook_example') do
+        port = $server ? $server.port : 0
+        make_http_request(:get, "http://localhost:#{port}/")
+      end
+      """
+    When I run `ruby before_http_request.rb run1.log --with-server`
+    Given that port numbers in "run1.log" are normalized to "7777"
+    Then the file "run1.log" should contain "before real request: get http://localhost:7777/"
+    When I run `ruby before_http_request.rb run2.log`
+    Then the file "run2.log" should not exist
+
+   Examples:
+      | configuration         | http_lib              |
+      | c.hook_into :fakeweb  | net/http              |
+      | c.hook_into :webmock  | net/http              |
+      | c.hook_into :webmock  | httpclient            |
+      | c.hook_into :webmock  | curb                  |
+      | c.hook_into :typhoeus | typhoeus              |
+      | c.hook_into :excon    | excon                 |
+      | c.hook_into :faraday  | faraday (w/ net_http) |
+

data/features/hooks/before_playback.feature

@@ -0,0 +1,184 @@
+Feature: before_playback hook
+
+  The `before_playback` hook is called before a cassette sets up its
+  stubs for playback.
+
+  Your block should accept up to 2 arguments.  The first argument will be
+  the HTTP interaction that is about to be used for play back.  The second
+  argument will be the current cassette.
+
+  You can also call `#ignore!` on the HTTP interaction to prevent VCR
+  from playing it back.
+
+  You can use tags to specify a cassette, otherwise your hook will apply to all cassettes.  Consider this code:
+
+      VCR.configure do |c|
+        c.before_playback(:twitter) { ... } # modify the interactions somehow
+      end
+
+      VCR.use_cassette('cassette_1', :tag => :twitter) { ... }
+      VCR.use_cassette('cassette_2') { ... }
+
+  In this example, the hook would apply to the first cassette but not the
+  second cassette.
+
+  Background:
+    Given a previously recorded cassette file "cassettes/example.yml" with:
+      """
+      ---
+      http_interactions:
+      - request:
+          method: get
+          uri: http://localhost:7777/
+          body:
+            encoding: UTF-8
+            string: ""
+          headers: {}
+        response:
+          status:
+            code: 200
+            message: OK
+          headers:
+            Content-Type:
+            - text/html;charset=utf-8
+            Content-Length:
+            - "20"
+          body:
+            encoding: UTF-8
+            string: previously recorded response
+          http_version: "1.1"
+        recorded_at: Tue, 01 Nov 2011 04:58:44 GMT
+      recorded_with: VCR 2.0.0
+      """
+
+  Scenario: Modify played back response
+    Given a file named "before_playback_example.rb" with:
+      """ruby
+      require 'vcr'
+
+      VCR.configure do |c|
+        c.hook_into :webmock
+        c.cassette_library_dir = 'cassettes'
+
+        c.before_playback do |interaction|
+          interaction.response.body = 'response from before_playback'
+        end
+      end
+
+      VCR.use_cassette('example') do
+        response = Net::HTTP.get_response('localhost', '/', 7777)
+        puts "Response: #{response.body}"
+      end
+      """
+    When I run `ruby before_playback_example.rb`
+    Then it should pass with "Response: response from before_playback"
+
+  Scenario: Modify played back response based on the cassette
+    Given a file named "before_playback_example.rb" with:
+      """ruby
+      require 'vcr'
+
+      VCR.configure do |c|
+        c.hook_into :webmock
+        c.cassette_library_dir = 'cassettes'
+
+        c.before_playback do |interaction, cassette|
+          interaction.response.body = "response for #{cassette.name} cassette"
+        end
+      end
+
+      VCR.use_cassette('example') do
+        response = Net::HTTP.get_response('localhost', '/', 7777)
+        puts "Response: #{response.body}"
+      end
+      """
+    When I run `ruby before_playback_example.rb`
+    Then it should pass with "Response: response for example cassette"
+
+  Scenario: Prevent playback by ignoring interaction in before_playback hook
+    Given a file named "before_playback_ignore.rb" with:
+      """ruby
+      $server = start_sinatra_app do
+        get('/') { "sinatra response" }
+      end
+
+      require 'vcr'
+
+      VCR.configure do |c|
+        c.hook_into :webmock
+        c.cassette_library_dir = 'cassettes'
+        c.before_playback { |i| i.ignore! }
+      end
+
+      VCR.use_cassette('localhost', :record => :new_episodes, :match_requests_on => [:method, :host, :path]) do
+        response = Net::HTTP.get_response('localhost', '/', $server.port)
+        puts "Response: #{response.body}"
+      end
+      """
+    When I run `ruby before_playback_ignore.rb`
+    Then it should pass with "Response: sinatra response"
+
+  Scenario: Multiple hooks are run in order
+    Given a file named "multiple_hooks.rb" with:
+      """ruby
+      require 'vcr'
+
+      VCR.configure do |c|
+        c.hook_into :webmock
+        c.cassette_library_dir = 'cassettes'
+
+        c.before_playback { puts "In before_playback hook 1" }
+        c.before_playback { puts "In before_playback hook 2" }
+      end
+
+      VCR.use_cassette('example', :record => :new_episodes) do
+        response = Net::HTTP.get_response('localhost', '/', 7777)
+        puts "Response: #{response.body}"
+      end
+      """
+    When I run `ruby multiple_hooks.rb`
+    Then it should pass with:
+      """
+      In before_playback hook 1
+      In before_playback hook 2
+      Response: previously recorded response
+      """
+
+  Scenario: Use tagging to apply hooks to only certain cassettes
+    Given a file named "tagged_hooks.rb" with:
+      """ruby
+      require 'vcr'
+
+      VCR.configure do |c|
+        c.hook_into :webmock
+        c.cassette_library_dir = 'cassettes'
+
+        c.before_playback(:tag_2) do |i|
+          puts "In before_playback hook for tag_2"
+        end
+      end
+
+      [:tag_1, :tag_2, nil].each do |tag|
+        puts
+        puts "Using tag: #{tag.inspect}"
+
+        VCR.use_cassette('example', :record => :new_episodes, :tag => tag) do
+          response = Net::HTTP.get_response('localhost', '/', 7777)
+          puts "Response: #{response.body}"
+        end
+      end
+      """
+    When I run `ruby tagged_hooks.rb`
+    Then it should pass with:
+      """
+      Using tag: :tag_1
+      Response: previously recorded response
+
+      Using tag: :tag_2
+      In before_playback hook for tag_2
+      Response: previously recorded response
+
+      Using tag: nil
+      Response: previously recorded response
+      """
+