vcr 2.0.0.beta2 → 2.0.0.rc1

data/features/getting_started.md

@@ -9,10 +9,9 @@ Create a file named `vcr_setup.rb` with content like:
 
     require 'vcr'
 
-    VCR.config do |c|
+    VCR.configure do |c|
       c.cassette_library_dir = 'vcr_cassettes'
-      c.stub_with :fakeweb
-      c.default_cassette_options = { :record => :once }
+      c.hook_into :fakeweb
     end
 
 Ensure this file is required by your test suite before any
@@ -23,10 +22,26 @@ of the tests are run.
 Run your tests.  Any tests that make HTTP requests using Net::HTTP will
 raise errors like:
 
-    FakeWeb::NetConnectNotAllowedError: Real HTTP connections are disabled.
-    Unregistered request: GET http://example.com/.
-    You can use VCR to automatically record this request and replay it later.
-    For more details, visit the VCR documentation at: http://relishapp.com/myronmarston/vcr
+    ================================================================================
+    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).
@@ -41,23 +56,25 @@ Run this test.  It will record the HTTP request to disk as a cassette (a
 test fixture), with content like:
 
     --- 
-    - !ruby/struct:VCR::HTTPInteraction 
-      request: !ruby/struct:VCR::Request 
-        method: :get
-        uri: http://example.com:80/
-        body: 
-        headers: 
-      response: !ruby/struct:VCR::Response 
-        status: !ruby/struct:VCR::ResponseStatus 
+    http_interactions:
+    - request:
+        method: get
+        uri: http://example.com/
+        body: ''
+        headers: {}
+      response:
+        status:
           code: 200
           message: OK
-        headers: 
-          content-type: 
+        headers:
+          Content-Type:
           - text/html;charset=utf-8
-          content-length: 
-          - "26"
-        body: This is the response body.
-        http_version: "1.1"
+          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

data/features/hooks/after_http_request.feature

@@ -0,0 +1,44 @@
+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)
+
+  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>")
+
+      start_sinatra_app(:port => 7777) do
+        get('/') { "Hello World" }
+      end
+
+      require 'vcr'
+
+      VCR.configure do |c|
+        <configuration>
+        c.cassette_library_dir = 'cassettes'
+        c.ignore_localhost = true
+        c.after_http_request do |request, response|
+          puts "Response for #{request.method} #{request.uri}: #{response.body}"
+        end
+      end
+
+      make_http_request(:get, "http://localhost:7777/")
+      """
+    When I run `ruby after_http_request.rb`
+    Then it should pass with "Response for get http://localhost:7777/: Hello World"
+
+   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,56 @@
+@exclude-18
+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
+      start_sinatra_app(:port => 7777) do
+        get('/') { "Response #{request_count += 1 }" }
+      end
+
+      require 'vcr'
+
+      VCR.configure do |c|
+        <configuration>
+        c.cassette_library_dir = 'cassettes'
+        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:7777/")
+      puts "Response for request 2: " + response_body_for(:get, "http://localhost:7777/")
+      """
+    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 "body: 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,44 @@
+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
+
+  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>")
+
+      start_sinatra_app(:port => 7777) do
+        get('/') { "Hello World" }
+      end
+
+      require 'vcr'
+
+      VCR.configure do |c|
+        <configuration>
+        c.cassette_library_dir = 'cassettes'
+        c.ignore_localhost = true
+        c.before_http_request do |request|
+          puts "before request: #{request.method} #{request.uri}"
+        end
+      end
+
+      make_http_request(:get, "http://localhost:7777/")
+      """
+    When I run `ruby before_http_request.rb`
+    Then it should pass with "before request: get http://localhost:7777/"
+
+   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,181 @@
+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.
+
+  If you don't your hook to apply to all cassettes, you can use tags for
+  this purpose.  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: ''
+          headers: {}
+        response:
+          status:
+            code: 200
+            message: OK
+          headers:
+            Content-Type:
+            - text/html;charset=utf-8
+            Content-Length:
+            - '20'
+          body: 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 :fakeweb
+        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 :fakeweb
+        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
+      start_sinatra_app(:port => 7777) do
+        get('/') { "sinatra response" }
+      end
+
+      require 'vcr'
+
+      VCR.configure do |c|
+        c.hook_into :fakeweb
+        c.cassette_library_dir = 'cassettes'
+        c.before_playback { |i| i.ignore! }
+      end
+
+      VCR.use_cassette('localhost', :record => :new_episodes) do
+        response = Net::HTTP.get_response('localhost', '/', 7777)
+        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 :fakeweb
+        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 :fakeweb
+        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
+      """
+

data/features/hooks/before_record.feature

@@ -0,0 +1,172 @@
+Feature: before_record hook
+
+  The `before_record` hook is called before a cassette is written to disk.
+  This can be used to modify the HTTP interaction before it is recorded.
+
+  Your block should accept up to 2 arguments.  The first argument will be
+  the HTTP interaction that is about to be written to disk.  The second
+  argument will be the current cassette.
+
+  You can also call `#ignore!` on the HTTP interaction to prevent VCR
+  from recording it.
+
+  If you don't your hook to apply to all cassettes, you can use tags for
+  this purpose.  Consider this code:
+
+      VCR.configure do |c|
+        c.before_record(: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.
+
+  Scenario: Modify recorded response
+    Given a file named "before_record_example.rb" with:
+      """ruby
+      start_sinatra_app(:port => 7777) do
+        get('/') { "Hello Earth" }
+      end
+
+      require 'vcr'
+
+      VCR.configure do |c|
+        c.hook_into :fakeweb
+        c.cassette_library_dir = 'cassettes'
+
+        c.before_record do |i|
+          i.response.body.sub!('Earth', 'World')
+        end
+      end
+
+      VCR.use_cassette('recording_example') do
+        Net::HTTP.get_response('localhost', '/', 7777)
+      end
+      """
+    When I run `ruby before_record_example.rb`
+    Then the file "cassettes/recording_example.yml" should contain "body: Hello World"
+     And the file "cassettes/recording_example.yml" should not contain "Earth"
+
+  Scenario: Modify recorded response based on the cassette
+    Given a file named "before_record_example.rb" with:
+      """ruby
+      start_sinatra_app(:port => 7777) do
+        get('/') { "Hello Earth" }
+      end
+
+      require 'vcr'
+
+      VCR.configure do |c|
+        c.hook_into :fakeweb
+        c.cassette_library_dir = 'cassettes'
+
+        c.before_record do |interaction, cassette|
+          interaction.response.body << " (#{cassette.name})"
+        end
+      end
+
+      VCR.use_cassette('recording_example') do
+        Net::HTTP.get_response('localhost', '/', 7777)
+      end
+      """
+    When I run `ruby before_record_example.rb`
+    Then the file "cassettes/recording_example.yml" should contain "body: Hello Earth (recording_example)"
+
+  Scenario: Prevent recording by ignoring interaction in before_record hook
+    Given a file named "before_record_ignore.rb" with:
+      """ruby
+      start_sinatra_app(:port => 7777) do
+        get('/') { "Hello World" }
+      end
+
+      require 'vcr'
+
+      VCR.configure do |c|
+        c.hook_into :fakeweb
+        c.cassette_library_dir = 'cassettes'
+        c.before_record { |i| i.ignore! }
+      end
+
+      VCR.use_cassette('recording_example') do
+        response = Net::HTTP.get_response('localhost', '/', 7777)
+        puts "Response: #{response.body}"
+      end
+      """
+    When I run `ruby before_record_ignore.rb`
+    Then it should pass with "Response: Hello World"
+    And the file "cassettes/recording_example.yml" should not exist
+
+  Scenario: Multiple hooks are run in order
+    Given a file named "multiple_hooks.rb" with:
+      """ruby
+      start_sinatra_app(:port => 7777) do
+        get('/') { "Hello World" }
+      end
+
+      require 'vcr'
+
+      VCR.configure do |c|
+        c.hook_into :fakeweb
+        c.cassette_library_dir = 'cassettes'
+
+        c.before_record { puts "In before_record hook 1" }
+        c.before_record { puts "In before_record 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:
+      """
+      Response: Hello World
+      In before_record hook 1
+      In before_record hook 2
+      """
+
+  Scenario: Use tagging to apply hook to only certain cassettes
+    Given a file named "tagged_hooks.rb" with:
+      """ruby
+      start_sinatra_app(:port => 7777) do
+        get('/') { "Hello World" }
+      end
+
+      require 'vcr'
+
+      VCR.configure do |c|
+        c.hook_into :fakeweb
+        c.cassette_library_dir = 'cassettes'
+
+        c.before_record(:tag_1) do
+          puts "In before_record hook for tag_1"
+        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: Hello World
+      In before_record hook for tag_1
+
+      Using tag: :tag_2
+      Response: Hello World
+
+      Using tag: nil
+      Response: Hello World
+      """
+