vcr 1.6.0 → 1.7.0

data/features/getting_started.md

@@ -0,0 +1,67 @@
+## Getting Started
+
+### Install it
+
+    [sudo] gem install vcr
+    [sudo] gem install fakeweb
+
+### Configure it
+
+Create a file named `vcr_setup.rb` with content like:
+
+    require 'vcr'
+
+    VCR.config do |c|
+      c.cassette_library_dir = 'vcr_cassettes'
+      c.stub_with :fakeweb
+      c.default_cassette_options = { :record => :once }
+    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:
+
+    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
+
+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:
+
+    --- 
+    - !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 
+          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"
+
+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/record_modes/all.feature

@@ -1,7 +1,9 @@
 Feature: :all
 
-  The `:all` record mode records all requests and does not
-  replay any previously recorded responds.
+  The `:all` record mode will:
+
+    - Record new interactions.
+    - Never replay previously recorded interactions.
 
   This can be temporarily used to force VCR to re-record
   a cassette (i.e. to ensure the responses are not out of date)

data/features/record_modes/new_episodes.feature

@@ -1,7 +1,13 @@
 Feature: :new_episodes
 
-  The `:new_episodes` record mode replays previously recorded
-  requests and records new ones.
+  The `:new_episodes` record mode will:
+
+    - Record new interactions.
+    - Replay previously recorded interactions.
+
+  It is similar to the `:once` record mode, but will _always_ record new
+  interactions, even if you have an existing recorded one that is similar
+  (but not identical, based on the `:match_request_on` option).
 
   Background:
     Given a file named "setup.rb" with:

data/features/record_modes/none.feature

@@ -1,7 +1,9 @@
 Feature: :none
 
-  The `:none` record mode allows previously recorded responses
-  to be replayed, but raises an error for any new requests.
+  The `:none` record mode will:
+
+    - Replay previously recorded interactions.
+    - Cause an error to be raised for any new requests.
 
   This is useful when your code makes potentially dangerous
   HTTP requests.  The `:none` record mode guarantees that no

data/features/record_modes/once.feature

@@ -0,0 +1,92 @@
+Feature: :once
+
+  The `:once` record mode will:
+
+    - Replay previously recorded interactions.
+    - Record new interactions if there is no cassette file.
+    - Cause an error to be raised for new requests if there is a cassette file.
+
+  It is similar to the `:new_episodes` record mode, but will prevent new,
+  unexpected requests from being made (i.e. because the request URI changed
+  or whatever).
+
+  `:once` is the default record mode, used when you do not set one.
+
+  Background:
+    Given a file named "setup.rb" with:
+      """
+      require 'vcr_cucumber_helpers'
+
+      start_sinatra_app(:port => 7777) do
+        get('/') { 'Hello' }
+      end
+
+      require 'vcr'
+
+      VCR.config do |c|
+        c.stub_with                :fakeweb
+        c.cassette_library_dir     = 'cassettes'
+      end
+      """
+    And a previously recorded cassette file "cassettes/example.yml" with:
+      """
+      --- 
+      - !ruby/struct:VCR::HTTPInteraction 
+        request: !ruby/struct:VCR::Request 
+          method: :get
+          uri: http://example.com:80/foo
+          body: 
+          headers: 
+        response: !ruby/struct:VCR::Response 
+          status: !ruby/struct:VCR::ResponseStatus 
+            code: 200
+            message: OK
+          headers: 
+            content-type: 
+            - text/html;charset=utf-8
+            content-length: 
+            - "20"
+          body: example.com response
+          http_version: "1.1"
+      """
+
+  Scenario: Previously recorded responses are replayed
+    Given a file named "replay_recorded_response.rb" with:
+      """
+      require 'setup'
+
+      VCR.use_cassette('example', :record => :once) do
+        response = Net::HTTP.get_response('example.com', '/foo')
+        puts "Response: #{response.body}"
+      end
+      """
+    When I run "ruby replay_recorded_response.rb"
+    Then it should pass with "Response: example.com response"
+
+  Scenario: New requests result in an error when the cassette file exists
+    Given a file named "error_for_new_requests_when_cassette_exists.rb" with:
+      """
+      require 'setup'
+
+      VCR.use_cassette('example', :record => :once) do
+        response = Net::HTTP.get_response('localhost', '/', 7777)
+        puts "Response: #{response.body}"
+      end
+      """
+    When I run "ruby error_for_new_requests_when_cassette_exists.rb"
+    Then it should fail with "Real HTTP connections are disabled"
+
+  Scenario: New requests get recorded when there is no cassette file
+    Given a file named "record_new_requests.rb" with:
+      """
+      require 'setup'
+
+      VCR.use_cassette('example', :record => :once) do
+        response = Net::HTTP.get_response('localhost', '/', 7777)
+        puts "Response: #{response.body}"
+      end
+      """
+    When I remove the file "cassettes/example.yml"
+    And I run "ruby record_new_requests.rb"
+    Then it should pass with "Response: Hello"
+    And the file "cassettes/example.yml" should contain "body: Hello"

data/features/step_definitions/cli_steps.rb

@@ -95,6 +95,24 @@ Then /^the file "([^"]*)" should contain each of these:$/ do |file_name, table|
   end
 end
 
+Then /^the file "([^"]*)" should contain:$/ do |file_name, expected_content|
+  check_file_content(file_name, expected_content, true)
+end
+
+Then /^the file "([^"]*)" should contain a YAML fragment like:$/ do |file_name, fragment|
+  if defined?(::Psych)
+    # psych serializes things slightly differently...
+    fragment = fragment.split("\n").map { |s| s.rstrip }.join("\n")
+  end
+
+  # JRuby serializes things a bit differently
+  if RUBY_PLATFORM == 'java'
+    fragment = fragment.gsub(/^(\s+\-)/,'  \1')
+  end
+
+  check_file_content(file_name, fragment, true)
+end
+
 Then /^the cassette "([^"]*)" should have the following response bodies:$/ do |file, table|
   interactions = in_current_dir { YAML.load_file(file) }
   actual_response_bodies = interactions.map { |i| i.response.body }

data/lib/vcr.rb

@@ -1,11 +1,18 @@
+require 'vcr/util/regexes'
+require 'vcr/util/variable_args_block_caller'
+require 'vcr/util/yaml'
+
 require 'vcr/cassette'
 require 'vcr/config'
-require 'vcr/deprecations'
 require 'vcr/request_matcher'
-require 'vcr/util/regexes'
 require 'vcr/version'
+
 require 'vcr/http_stubbing_adapters/common'
 
+require 'vcr/deprecations/cassette'
+require 'vcr/deprecations/config'
+require 'vcr/deprecations/http_stubbing_adapters/common'
+
 require 'vcr/structs/normalizers/body'
 require 'vcr/structs/normalizers/header'
 require 'vcr/structs/normalizers/status_message'
@@ -16,12 +23,13 @@ require 'vcr/structs/response'
 require 'vcr/structs/response_status'
 
 module VCR
+  include VariableArgsBlockCaller
   extend self
 
   autoload :BasicObject,        'vcr/util/basic_object'
-  autoload :CucumberTags,       'vcr/cucumber_tags'
+  autoload :CucumberTags,       'vcr/test_frameworks/cucumber'
   autoload :InternetConnection, 'vcr/util/internet_connection'
-  autoload :RSpec,              'vcr/rspec'
+  autoload :RSpec,              'vcr/test_frameworks/rspec'
 
   LOCALHOST_ALIASES = %w( localhost 127.0.0.1 0.0.0.0 )
 
@@ -63,8 +71,7 @@ module VCR
     cassette = insert_cassette(*args)
 
     begin
-      # yield the cassette if the block accepts an argument or variable args
-      block.arity == 0 ? block.call : block.call(cassette)
+      call_block(block, cassette)
     ensure
       eject_cassette
     end

data/lib/vcr/cassette.rb

@@ -1,5 +1,4 @@
 require 'fileutils'
-require 'yaml'
 require 'erb'
 require 'set'
 
@@ -7,13 +6,21 @@ require 'vcr/cassette/reader'
 
 module VCR
   class Cassette
-    VALID_RECORD_MODES = [:all, :none, :new_episodes]
+    VALID_RECORD_MODES = [:all, :none, :new_episodes, :once]
 
     attr_reader :name, :record_mode, :match_requests_on, :erb, :re_record_interval, :tag
 
     def initialize(name, options = {})
       options = VCR::Config.default_cassette_options.merge(options)
-      invalid_options = options.keys - [:record, :erb, :allow_real_http, :match_requests_on, :re_record_interval, :tag]
+      invalid_options = options.keys - [
+        :record,
+        :erb,
+        :allow_real_http,
+        :match_requests_on,
+        :re_record_interval,
+        :tag,
+        :update_content_length_header
+      ]
 
       if invalid_options.size > 0
         raise ArgumentError.new("You passed the following invalid options to VCR::Cassette.new: #{invalid_options.inspect}.")
@@ -26,6 +33,7 @@ module VCR
       @re_record_interval = options[:re_record_interval]
       @tag                = options[:tag]
       @record_mode        = :all if should_re_record?
+      @update_content_length_header = options[:update_content_length_header]
 
       deprecate_old_cassette_options(options)
       raise_error_unless_valid_record_mode
@@ -57,6 +65,10 @@ module VCR
       File.join(VCR::Config.cassette_library_dir, "#{sanitized_name}.yml") if VCR::Config.cassette_library_dir
     end
 
+    def update_content_length_header?
+      @update_content_length_header
+    end
+
     private
 
     def sanitized_name
@@ -65,7 +77,7 @@ module VCR
 
     def raise_error_unless_valid_record_mode
       unless VALID_RECORD_MODES.include?(record_mode)
-        raise ArgumentError.new("#{record_mode} is not a valid cassette record mode.  Valid options are: #{VALID_RECORD_MODES.inspect}")
+        raise ArgumentError.new("#{record_mode} is not a valid cassette record mode.  Valid modes are: #{VALID_RECORD_MODES.inspect}")
       end
     end
 
@@ -77,7 +89,11 @@ module VCR
     end
 
     def should_allow_http_connections?
-      record_mode != :none
+      case record_mode
+        when :none; false
+        when :once; !File.size?(file)
+        else true
+      end
     end
 
     def should_stub_requests?
@@ -101,18 +117,23 @@ module VCR
       VCR.http_stubbing_adapter.create_stubs_checkpoint(self)
       if file && File.size?(file)
         begin
-          interactions = YAML.load(raw_yaml_content)
-          invoke_hook(:before_playback, interactions)
-
-          interactions.reject! do |i|
-            i.request.uri.is_a?(String) && VCR::Config.uri_should_be_ignored?(i.request.uri)
-          end
-
-          recorded_interactions.replace(interactions)
-        rescue TypeError
+          interactions = VCR::YAML.load(raw_yaml_content)
+        rescue TypeError, ArgumentError # Syck raises TypeError, Psych raises ArgumentError
           raise unless raw_yaml_content =~ /VCR::RecordedResponse/
           raise "The VCR cassette #{sanitized_name}.yml uses an old format that is now deprecated.  VCR provides a rake task to migrate your old cassettes to the new format.  See http://github.com/myronmarston/vcr/blob/master/CHANGELOG.md for more info."
         end
+
+        invoke_hook(:before_playback, interactions)
+
+        interactions.reject! do |i|
+          i.request.uri.is_a?(String) && VCR::Config.uri_should_be_ignored?(i.request.uri)
+        end
+
+        if update_content_length_header?
+          interactions.each { |i| i.response.update_content_length_header }
+        end
+
+        recorded_interactions.replace(interactions)
       end
 
       if should_stub_requests?
@@ -152,7 +173,7 @@ module VCR
 
       directory = File.dirname(file)
       FileUtils.mkdir_p directory unless File.exist?(directory)
-      File.open(file, 'w') { |f| f.write interactions.to_yaml }
+      File.open(file, 'w') { |f| f.write VCR::YAML.dump(interactions) }
     end
 
     def invoke_hook(type, interactions)

data/lib/vcr/config.rb

@@ -1,9 +1,10 @@
 require 'fileutils'
-require 'vcr/hooks'
+require 'vcr/util/hooks'
 
 module VCR
   module Config
     include VCR::Hooks
+    include VCR::VariableArgsBlockCaller
     extend self
 
     define_hook :before_record
@@ -18,7 +19,8 @@ module VCR
     attr_writer :default_cassette_options
     def default_cassette_options
       @default_cassette_options ||= {}
-      @default_cassette_options.merge!(:match_requests_on => RequestMatcher::DEFAULT_MATCH_ATTRIBUTES) unless @default_cassette_options.has_key?(:match_requests_on)
+      @default_cassette_options[:match_requests_on] ||= RequestMatcher::DEFAULT_MATCH_ATTRIBUTES
+      @default_cassette_options[:record] ||= :once
       @default_cassette_options
     end
 
@@ -57,6 +59,16 @@ module VCR
       !!@allow_http_connections_when_no_cassette
     end
 
+    def filter_sensitive_data(placeholder, tag = nil, &block)
+      before_record(tag) do |interaction|
+        interaction.filter!(call_block(block, interaction), placeholder)
+      end
+
+      before_playback(tag) do |interaction|
+        interaction.filter!(placeholder, call_block(block, interaction))
+      end
+    end
+
     def uri_should_be_ignored?(uri)
       uri = URI.parse(uri) unless uri.respond_to?(:host)
       ignored_hosts.include?(uri.host)

data/lib/vcr/deprecations/cassette.rb

@@ -0,0 +1,29 @@
+module VCR
+  class Cassette
+    def allow_real_http_requests_to?(uri)
+      warn "WARNING: VCR::Cassette#allow_real_http_requests_to? is deprecated and should no longer be used."
+      VCR::Config.uri_should_be_ignored?(uri.to_s)
+    end
+
+    private
+
+      def deprecate_old_cassette_options(options)
+        message = "VCR's :allow_real_http cassette option is deprecated.  Instead, use the ignore_localhost configuration option."
+        if options[:allow_real_http] == :localhost
+          @original_ignored_hosts = VCR::Config.ignored_hosts.dup
+          VCR::Config.ignored_hosts.clear
+          VCR::Config.ignore_hosts *VCR::LOCALHOST_ALIASES
+          Kernel.warn "WARNING: #{message}"
+        elsif options[:allow_real_http]
+          raise ArgumentError.new(message)
+        end
+      end
+
+      def restore_ignore_localhost_for_deprecation
+        if defined?(@original_ignored_hosts)
+          VCR::Config.ignored_hosts.clear
+          VCR::Config.ignore_hosts *@original_ignored_hosts
+        end
+      end
+    end
+end