vcr 2.0.0.rc1 → 2.0.0.rc2

data/features/support/env.rb

@@ -1,6 +1,7 @@
 require 'rubygems'
 require 'bundler'
 Bundler.setup
+require 'limited_red/plugins/cucumber' unless ENV['CI']
 
 require 'ruby-debug' if !defined?(RUBY_ENGINE) && RUBY_VERSION != '1.9.3' && !ENV['CI']
 
@@ -14,6 +15,12 @@ end
 Before do
   load_paths, requires = ['../../lib'], []
 
+  # Put any bundler-managed gems (such as :git gems) on the load path for when aruba shells out.
+  # Alternatively, we could hook up aruba to use bundler when it shells out, but invoking bundler
+  # for each and every time aruba starts ruby would slow everything down. We really only need it for
+  # bundler-managed gems.
+  load_paths.push($LOAD_PATH.grep %r|bundler/gems|)
+
   if RUBY_VERSION < '1.9'
     requires << "rubygems"
   else
@@ -24,12 +31,6 @@ Before do
   requires.map! { |r| "-r#{r}" }
   set_env('RUBYOPT', "-I#{load_paths.join(':')} #{requires.join(' ')}")
 
-  if RUBY_PLATFORM == 'java'
-    # ideas taken from: http://blog.headius.com/2010/03/jruby-startup-time-tips.html
-    set_env('JRUBY_OPTS', '-X-C') # disable JIT since these processes are so short lived
-    set_env('JAVA_OPTS', '-d32') # force jRuby to use client JVM for faster startup times
-  end
-
   if additional_paths.any?
     existing_paths = ENV['PATH'].split(':')
     set_env('PATH', (additional_paths + existing_paths).join(':'))

data/features/support/vcr_cucumber_helpers.rb

@@ -38,6 +38,7 @@ def start_sinatra_app(options, &block)
   require 'sinatra'
   require 'support/vcr_localhost_server'
   klass = Class.new(Sinatra::Base)
+  klass.disable :protection
   klass.class_eval(&block)
 
   VCR::LocalhostServer.new(klass.new, options[:port])

data/features/test_frameworks/cucumber.feature

@@ -96,10 +96,10 @@ Feature: Usage with Cucumber
       |   GET http://localhost:7777/disallowed_1                                          |
       | An HTTP request has been made that VCR does not know how to handle:               |
       |   GET http://localhost:7777/disallowed_2                                          |
-    And the file "features/cassettes/cucumber_tags/localhost_request.yml" should contain "body: Hello localhost_request_1"
-    And the file "features/cassettes/cucumber_tags/localhost_request.yml" should contain "body: Hello localhost_request_2"
-    And the file "features/cassettes/nested_cassette.yml" should contain "body: Hello nested_cassette"
-    And the file "features/cassettes/allowed.yml" should contain "body: Hello allowed"
+    And the file "features/cassettes/cucumber_tags/localhost_request.yml" should contain "Hello localhost_request_1"
+    And the file "features/cassettes/cucumber_tags/localhost_request.yml" should contain "Hello localhost_request_2"
+    And the file "features/cassettes/nested_cassette.yml" should contain "Hello nested_cassette"
+    And the file "features/cassettes/allowed.yml" should contain "Hello allowed"
 
     # Run again without the server; we'll get the same responses because VCR
     # will replay the recorded responses.
@@ -110,8 +110,8 @@ Feature: Usage with Cucumber
       |   GET http://localhost:7777/disallowed_1                                          |
       | An HTTP request has been made that VCR does not know how to handle:               |
       |   GET http://localhost:7777/disallowed_2                                          |
-    And the file "features/cassettes/cucumber_tags/localhost_request.yml" should contain "body: Hello localhost_request_1"
-    And the file "features/cassettes/cucumber_tags/localhost_request.yml" should contain "body: Hello localhost_request_2"
-    And the file "features/cassettes/nested_cassette.yml" should contain "body: Hello nested_cassette"
-    And the file "features/cassettes/allowed.yml" should contain "body: Hello allowed"
+    And the file "features/cassettes/cucumber_tags/localhost_request.yml" should contain "Hello localhost_request_1"
+    And the file "features/cassettes/cucumber_tags/localhost_request.yml" should contain "Hello localhost_request_2"
+    And the file "features/cassettes/nested_cassette.yml" should contain "Hello nested_cassette"
+    And the file "features/cassettes/allowed.yml" should contain "Hello allowed"
 

data/features/test_frameworks/rspec_macro.feature

@@ -76,8 +76,8 @@ Feature: Usage with RSpec macro
       """
     When I run `rspec spec/vcr_example_spec.rb`
     Then the output should contain "2 examples, 0 failures"
-     And the file "spec/cassettes/VCR-RSpec_integration/without_an_explicit_cassette_name.yml" should contain "body: Hello"
-     And the file "spec/cassettes/net_http_example.yml" should contain "body: Hello"
+     And the file "spec/cassettes/VCR-RSpec_integration/without_an_explicit_cassette_name.yml" should contain "Hello"
+     And the file "spec/cassettes/net_http_example.yml" should contain "Hello"
 
   @rspec-1 @exclude-jruby
   Scenario: Use `use_vcr_cassette` macro with RSpec 1
@@ -101,6 +101,6 @@ Feature: Usage with RSpec macro
       """
     When I run `spec spec/vcr_example_spec.rb`
     Then the output should contain "2 examples, 0 failures"
-     And the file "spec/cassettes/VCR-RSpec_integration/without_an_explicit_cassette_name.yml" should contain "body: Hello"
-     And the file "spec/cassettes/net_http_example.yml" should contain "body: Hello"
+     And the file "spec/cassettes/VCR-RSpec_integration/without_an_explicit_cassette_name.yml" should contain "Hello"
+     And the file "spec/cassettes/net_http_example.yml" should contain "Hello"
 

data/features/test_frameworks/rspec_metadata.feature

@@ -31,7 +31,7 @@ Feature: Usage with RSpec metadata
 
   Scenario: Use `:vcr` metadata
     Given a file named "spec/vcr_example_spec.rb" with:
-      """
+      """ruby
       start_sinatra_app(:port => 7777) do
         get('/') { "Hello" }
       end
@@ -66,14 +66,14 @@ Feature: Usage with RSpec metadata
       """
     When I run `rspec spec/vcr_example_spec.rb`
     Then it should pass with "4 examples, 0 failures"
-     And the file "spec/cassettes/VCR_example_group_metadata/records_an_http_request.yml" should contain "body: Hello"
-     And the file "spec/cassettes/VCR_example_group_metadata/records_another_http_request.yml" should contain "body: Hello"
-     And the file "spec/cassettes/VCR_example_group_metadata/in_a_nested_example_group/records_another_one.yml" should contain "body: Hello"
-     And the file "spec/cassettes/VCR_example_metadata/records_an_http_request.yml" should contain "body: Hello"
+     And the file "spec/cassettes/VCR_example_group_metadata/records_an_http_request.yml" should contain "Hello"
+     And the file "spec/cassettes/VCR_example_group_metadata/records_another_http_request.yml" should contain "Hello"
+     And the file "spec/cassettes/VCR_example_group_metadata/in_a_nested_example_group/records_another_one.yml" should contain "Hello"
+     And the file "spec/cassettes/VCR_example_metadata/records_an_http_request.yml" should contain "Hello"
 
   Scenario: Pass a hash to set the cassette options
     Given a file named "spec/vcr_example_spec.rb" with:
-      """
+      """ruby
       require 'spec_helper'
 
       describe "Using an options hash", :vcr => { :cassette_name => "example", :record => :new_episodes } do

data/features/test_frameworks/shoulda.feature

@@ -56,7 +56,7 @@ Feature: Usage with Shoulda
     When I set the "SERVER" environment variable to "true"
      And I run `ruby -Itest test/vcr_example_test.rb`
     Then it should pass with "1 tests, 1 assertions, 0 failures, 0 errors"
-    And the file "test/fixtures/vcr_cassettes/shoulda_example.yml" should contain "body: Hello"
+    And the file "test/fixtures/vcr_cassettes/shoulda_example.yml" should contain "Hello"
 
     # Run again without starting the sinatra server so the response will be replayed
     When I set the "SERVER" environment variable to "false"

data/features/test_frameworks/test_unit.feature

@@ -38,7 +38,7 @@ Feature: Usage with Test::Unit
     When I set the "SERVER" environment variable to "true"
      And I run `ruby -Itest test/vcr_example_test.rb`
     Then it should pass with "1 tests, 1 assertions, 0 failures, 0 errors"
-    And the file "test/fixtures/vcr_cassettes/test_unit_example.yml" should contain "body: Hello"
+    And the file "test/fixtures/vcr_cassettes/test_unit_example.yml" should contain "Hello"
 
     # Run again without starting the sinatra server so the response will be replayed
     When I set the "SERVER" environment variable to "false"

data/lib/vcr.rb

@@ -1,3 +1,4 @@
+require 'vcr/util/logger'
 require 'vcr/util/variable_args_block_caller'
 
 require 'vcr/cassette'
@@ -11,7 +12,9 @@ require 'vcr/request_matcher_registry'
 require 'vcr/structs'
 require 'vcr/version'
 
-
+# The main entry point for VCR.
+# @note This module is extended onto itself; thus, the methods listed
+#  here as instance methods are available directly off of VCR.
 module VCR
   include VariableArgsBlockCaller
   include Errors
@@ -27,10 +30,75 @@ module VCR
     autoload :Rack,              'vcr/middleware/rack'
   end
 
+  # The currently active cassette.
+  #
+  # @return [nil, VCR::Cassette] The current cassette or nil if there is
+  #  no current cassette.
   def current_cassette
     cassettes.last
   end
 
+  # Inserts the named cassette using the given cassette options.
+  # New HTTP interactions, if allowed by the cassette's `:record` option, will
+  # be recorded to the cassette. The cassette's existing HTTP interactions
+  # will be used to stub requests, unless prevented by the cassete's
+  # `:record` option.
+  #
+  # @example
+  #   VCR.insert_cassette('twitter', :record => :new_episodes)
+  #
+  #   # ...later, after making an HTTP request:
+  #
+  #   VCR.eject_cassette
+  #
+  # @param name [#to_s] The name of the cassette. VCR will sanitize
+  #                     this to ensure it is a valid file name.
+  # @param options [Hash] The cassette options. The given options will
+  #  be merged with the configured default_cassette_options.
+  # @option options :record [:all, :none, :new_episodes, :once] The record mode.
+  # @option options :erb [Boolean, Hash] Whether or not to evaluate the
+  #  cassette as an ERB template. Defaults to false. A hash can be used
+  #  to provide the ERB template with local variables.
+  # @option options :match_requests_on [Array<Symbol, #call>] List of request matchers
+  #  to use to determine what recorded HTTP interaction to replay. Defaults to
+  #  [:method, :uri]. The built-in matchers are :method, :uri, :host, :path, :headers
+  #  and :body. You can also pass the name of a registered custom request matcher or
+  #  any object that responds to #call.
+  # @option options :re_record_interval [Integer] When given, the
+  #  cassette will be re-recorded at the given interval, in seconds.
+  # @option options :tag [Symbol] Used to apply tagged `before_record`
+  #  and `before_playback` hooks to the cassette.
+  # @option options :tags [Array<Symbol>] Used to apply multiple tags to
+  #  a cassette so that tagged `before_record` and `before_playback` hooks
+  #  will apply to the cassette.
+  # @option options :update_content_length_header [Boolean] Whether or
+  #  not to overwrite the Content-Length header of the responses to
+  #  match the length of the response body. Defaults to false.
+  # @option options :allow_playback_repeats [Boolean] Whether or not to
+  #  allow a single HTTP interaction to be played back multiple times.
+  #  Defaults to false.
+  # @option options :exclusive [Boolean] Whether or not to use only this
+  #  cassette and to completely ignore any cassettes in the cassettes stack.
+  #  Defaults to false.
+  # @option options :serialize_with [Symbol] Which serializer to use.
+  #  Valid values are :yaml, :syck, :psych, :json or any registered
+  #  custom serializer. Defaults to :yaml.
+  # @option options :preserve_exact_body_bytes [Boolean] Whether or not
+  #  to base64 encode the bytes of the requests and responses for this cassette
+  #  when serializing it. See also `VCR::Configuration#preserve_exact_body_bytes`.
+  #
+  # @return [VCR::Cassette] the inserted cassette
+  #
+  # @raise [ArgumentError] when the given cassette is already being used.
+  # @raise [VCR::Errors::TurnedOffError] when VCR has been turned off
+  #  without using the :ignore_cassettes option.
+  # @raise [VCR::Errors::MissingERBVariableError] when the `:erb` option
+  #  is used and the ERB template requires variables that you did not provide.
+  #
+  # @note If you use this method you _must_ call `eject_cassette` when you
+  #  are done. It is generally recommended that you use {#use_cassette}
+  #  unless your code-under-test cannot be run as a block.
+  #
   def insert_cassette(name, options = {})
     if turned_on?
       if cassettes.any? { |c| c.name == name }
@@ -47,14 +115,36 @@ module VCR
     end
   end
 
+  # Ejects the current cassette. The cassette will no longer be used.
+  # In addition, any newly recorded HTTP interactions will be written to
+  # disk.
+  #
+  # @return [VCR::Cassette, nil] the ejected cassette if there was one
   def eject_cassette
-    cassette = cassettes.pop
+    cassette = cassettes.last
     cassette.eject if cassette
-    cassette
+    cassettes.pop
   end
 
-  def use_cassette(*args, &block)
-    cassette = insert_cassette(*args)
+  # Inserts a cassette using the given name and options, runs the given
+  # block, and ejects the cassette.
+  #
+  # @example
+  #   VCR.use_cassette('twitter', :record => :new_episodes) do
+  #     # make an HTTP request
+  #   end
+  #
+  # @param (see #insert_cassette)
+  # @option (see #insert_cassette)
+  # @yield Block to run while this cassette is in use.
+  # @yieldparam cassette [(optional) VCR::Cassette] the cassette that has
+  #  been inserted.
+  # @raise (see #insert_cassette)
+  # @return [void]
+  # @see #insert_cassette
+  # @see #eject_cassette
+  def use_cassette(name, options = {}, &block)
+    cassette = insert_cassette(name, options)
 
     begin
       call_block(block, cassette)
@@ -63,45 +153,76 @@ module VCR
     end
   end
 
+  # @private
   def http_interactions
     return current_cassette.http_interactions if current_cassette
     VCR::Cassette::HTTPInteractionList::NullList
   end
 
+  # @private
   def real_http_connections_allowed?
     return current_cassette.recording? if current_cassette
     configuration.allow_http_connections_when_no_cassette? || @turned_off
   end
 
+  # @return [RequestMatcherRegistry] the request matcher registry
   def request_matchers
     @request_matchers ||= RequestMatcherRegistry.new
   end
 
+  # @private
   def request_ignorer
     @request_ignorer ||= RequestIgnorer.new
   end
 
+  # @private
   def library_hooks
     @library_hooks ||= LibraryHooks.new
   end
 
+  # @private
   def cassette_serializers
     @cassette_serializers ||= Cassette::Serializers.new
   end
 
+  # @return [VCR::Configuration] the VCR configuration.
   def configuration
     @configuration ||= Configuration.new
   end
 
+  # Used to configure VCR.
+  #
+  # @example
+  #    VCR.configure do |c|
+  #      c.some_config_option = true
+  #    end
+  #
+  # @yield the configuration block
+  # @yieldparam config [VCR::Configuration] the configuration object
+  # @return [void]
   def configure
     yield configuration
   end
 
+  # Sets up `Before` and `After` cucumber hooks in order to
+  # use VCR with particular cucumber tags.
+  #
+  # @example
+  #   VCR.cucumber_tags do |t|
+  #     t.tags "tag1", "tag2"
+  #     t.tag "@some_other_tag", :record => :new_episodes
+  #   end
+  #
+  # @yield the cucumber tags configuration block
+  # @yieldparam t [VCR::CucumberTags] Cucumber tags config object
+  # @return [void]
+  # @see VCR::CucumberTags#tags
   def cucumber_tags(&block)
     main_object = eval('self', block.binding)
     yield VCR::CucumberTags.new(main_object)
   end
 
+  # @private
   def record_http_interaction(interaction)
     return unless cassette = current_cassette
     return if VCR.request_ignorer.ignore?(interaction.request)
@@ -109,6 +230,14 @@ module VCR
     cassette.record_http_interaction(interaction)
   end
 
+  # Turns VCR off for the duration of a block.
+  #
+  # @param (see #turn_off!)
+  # @return [void]
+  # @raise (see #turn_off!)
+  # @see #turn_off!
+  # @see #turn_on!
+  # @see #turned_on?
   def turned_off(options = {})
     turn_off!(options)
 
@@ -119,6 +248,16 @@ module VCR
     end
   end
 
+  # Turns VCR off, so that it no longer handles every HTTP request.
+  #
+  # @param options [Hash] hash of options
+  # @option options :ignore_cassettes [Boolean] controls what happens when a cassette is
+  #  inserted while VCR is turned off. If +true+ is passed, the cassette insertion
+  #  will be ignored; otherwise a {VCR::Errors::TurnedOffError} will be raised.
+  #
+  # @return [void]
+  # @raise [VCR::Errors::CassetteInUseError] if there is currently a cassette in use
+  # @raise [ArgumentError] if you pass an invalid option
   def turn_off!(options = {})
     if VCR.current_cassette
       raise CassetteInUseError.new("A VCR cassette is currently in use.  You must eject it before you can turn VCR off.")
@@ -133,14 +272,26 @@ module VCR
     @turned_off = true
   end
 
+  # Turns on VCR, if it has previously been turned off.
+  # @return [void]
+  # @see #turn_off!
+  # @see #turned_off
+  # @see #turned_on?
   def turn_on!
     @turned_off = false
   end
 
+  # @return whether or not VCR is turned on
+  # @note Normally VCR is _always_ turned on; it will only be off if you have
+  #  explicitly turned it off.
+  # @see #turn_on!
+  # @see #turn_off!
+  # @see #turned_off
   def turned_on?
     !@turned_off
   end
 
+  # @private
   def ignore_cassettes?
     @ignore_cassettes
   end

data/lib/vcr/cassette.rb

@@ -6,17 +6,51 @@ require 'vcr/cassette/reader'
 require 'vcr/cassette/serializers'
 
 module VCR
+  # The media VCR uses to store HTTP interactions for later re-use.
   class Cassette
+    include Logger
+
+    # The supported record modes.
+    #
+    #   * :all -- Record every HTTP interactions; do not play any back.
+    #   * :none -- Do not record any HTTP interactions; play them back.
+    #   * :new_episodes -- Playback previously recorded HTTP interactions and record new ones.
+    #   * :once -- Record the HTTP interactions if the cassette has not already been recorded;
+    #              otherwise, playback the HTTP interactions.
     VALID_RECORD_MODES = [:all, :none, :new_episodes, :once]
 
-    attr_reader :name, :record_mode, :match_requests_on, :erb, :re_record_interval, :tag
+    # @return [#to_s] The name of the cassette. Used to determine the cassette's file name.
+    # @see #file
+    attr_reader :name
 
+    # @return [Symbol] The record mode. Determines whether the cassette records HTTP interactions,
+    #  plays them back, or does both.
+    attr_reader :record_mode
+
+    # @return [Array<Symbol, #call>] List of request matchers. Used to find a response from an
+    #  existing HTTP interaction to play back.
+    attr_reader :match_requests_on
+
+    # @return [Boolean, Hash] The cassette's ERB option. The file will be treated as an
+    #  ERB template if this has a truthy value. A hash, if provided, will be used as local
+    #  variables for the ERB template.
+    attr_reader :erb
+
+    # @return [Integer, nil] How frequently (in seconds) the cassette should be re-recorded.
+    attr_reader :re_record_interval
+
+    # @return [Array<Symbol>] If set, {VCR::Configuration#before_record} and
+    #  {VCR::Configuration#before_playback} hooks with a corresponding tag will apply.
+    attr_reader :tags
+
+    # @param (see VCR#insert_cassette)
+    # @see VCR#insert_cassette
     def initialize(name, options = {})
       options = VCR.configuration.default_cassette_options.merge(options)
       invalid_options = options.keys - [
-        :record, :erb, :match_requests_on, :re_record_interval, :tag,
+        :record, :erb, :match_requests_on, :re_record_interval, :tag, :tags,
         :update_content_length_header, :allow_playback_repeats, :exclusive,
-        :serialize_with
+        :serialize_with, :preserve_exact_body_bytes
       ]
 
       if invalid_options.size > 0
@@ -28,8 +62,9 @@ module VCR
       @erb                          = options[:erb]
       @match_requests_on            = options[:match_requests_on]
       @re_record_interval           = options[:re_record_interval]
-      @tag                          = options[:tag]
-      @update_content_length_header = options[:update_content_length_header]
+      @tags                         = Array(options.fetch(:tags) { options[:tag] })
+      @tags                         << :update_content_length_header if options[:update_content_length_header]
+      @tags                         << :preserve_exact_body_bytes if options[:preserve_exact_body_bytes]
       @allow_playback_repeats       = options[:allow_playback_repeats]
       @exclusive                    = options[:exclusive]
       @serializer                   = VCR.cassette_serializers[options[:serialize_with]]
@@ -37,55 +72,46 @@ module VCR
       @parent_list                  = @exclusive ? HTTPInteractionList::NullList : VCR.http_interactions
 
       raise_error_unless_valid_record_mode
+
+      log "Initialized with options: #{options.inspect}"
     end
 
+    # Ejects the current cassette. The cassette will no longer be used.
+    # In addition, any newly recorded HTTP interactions will be written to
+    # disk.
     def eject
       write_recorded_interactions_to_disk
     end
 
-    def previously_recorded_interactions
-      @previously_recorded_interactions ||= if file && File.size?(file)
-        deserialized_hash['http_interactions'].map { |h| HTTPInteraction.from_hash(h) }.tap do |interactions|
-          invoke_hook(:before_playback, interactions)
-
-          interactions.reject! do |i|
-            i.request.uri.is_a?(String) && VCR.request_ignorer.ignore?(i.request)
-          end
-
-          if update_content_length_header?
-            interactions.each { |i| i.response.update_content_length_header }
-          end
-        end
-      else
-        []
-      end
-    end
-
+    # @private
     def http_interactions
       @http_interactions ||= HTTPInteractionList.new \
         should_stub_requests? ? previously_recorded_interactions : [],
         match_requests_on,
         @allow_playback_repeats,
-        @parent_list
+        @parent_list,
+        log_prefix
     end
 
+    # @private
     def record_http_interaction(interaction)
+      log "Recorded HTTP interaction #{request_summary(interaction.request)} => #{response_summary(interaction.response)}"
       new_recorded_interactions << interaction
     end
 
+    # @private
     def new_recorded_interactions
       @new_recorded_interactions ||= []
     end
 
+    # @return [String] The file for this cassette.
+    # @note VCR will take care of sanitizing the cassette name to make it a valid file name.
     def file
       return nil unless VCR.configuration.cassette_library_dir
       File.join(VCR.configuration.cassette_library_dir, "#{sanitized_name}.#{@serializer.file_extension}")
     end
 
-    def update_content_length_header?
-      @update_content_length_header
-    end
-
+    # @return [Boolean] Whether or not the cassette is recording.
     def recording?
       case record_mode
         when :none; false
@@ -94,6 +120,7 @@ module VCR
       end
     end
 
+    # @return [Hash] The hash that will be serialized when the cassette is written to disk.
     def serializable_hash
       {
         "http_interactions" => interactions_to_record.map(&:to_hash),
@@ -103,6 +130,20 @@ module VCR
 
   private
 
+    def previously_recorded_interactions
+      @previously_recorded_interactions ||= if file && File.size?(file)
+        deserialized_hash['http_interactions'].map { |h| HTTPInteraction.from_hash(h) }.tap do |interactions|
+          invoke_hook(:before_playback, interactions)
+
+          interactions.reject! do |i|
+            i.request.uri.is_a?(String) && VCR.request_ignorer.ignore?(i.request)
+          end
+        end
+      else
+        []
+      end
+    end
+
     def sanitized_name
       name.to_s.gsub(/[^\w\-\/]+/, '_')
     end
@@ -170,8 +211,9 @@ module VCR
 
     def invoke_hook(type, interactions)
       interactions.delete_if do |i|
-        VCR.configuration.invoke_tagged_hook(type, tag, i, self)
-        i.ignored?
+        i.hook_aware.tap do |hw|
+          VCR.configuration.invoke_hook(type, hw, self)
+        end.ignored?
       end
     end
 
@@ -187,5 +229,13 @@ module VCR
         end
       end
     end
+
+    def log_prefix
+      @log_prefix ||= "[Cassette: '#{name}'] "
+    end
+
+    def request_summary(request)
+      super(request, match_requests_on)
+    end
   end
 end