vcr 0.4.1 → 1.0.0

data/CHANGELOG.md

@@ -1,5 +1,39 @@
 #Changelog
 
+## 1.0.0 (June 22, 2010)
+
+* New Features
+  * Added support for [HTTPClient](http://github.com/nahi/httpclient), [Patron](http://github.com/toland/patron) and
+    [em-http-request](http://github.com/igrigorik/em-http-request) when WebMock is used.  Any future http libraries
+    WebMock supports should (theoretically, at least) work without any VCR code changes.  Thanks to 
+    [Bartosz Blimke](http://github.com/bblimke) for adding the necessary code to WebMock to make this happen!
+  * Added support for dynamic responses using ERB.  A cassette will be evaluated as ERB before the YAML
+    is deserialized if you pass it an `:erb => true` option.  You can pass variables using
+    `:erb => { :var1 => 'some value', :var2 => 'another value' }`.
+  * Added `ignore_localhost` configuration setting, which defaults to false.  Setting it true does the following:
+    * Localhost requests will proceed as normal.  The "Real HTTP connections are disabled" error will not occur.
+    * Localhost requests will not be recorded.
+    * Previously recorded localhost requests will not be replayed.
+  * Exposed the version number:
+    * `VCR.version`       => string (in the format "major.minor.patch")
+    * `VCR.version.parts` => array of integers
+    * `VCR.version.major` => integer
+    * `VCR.version.minor` => integer
+    * `VCR.version.patch` => integer
+  * Added test coverage and documentation of using a regex for non-deterministic URLs (i.e. URLs that include
+    a timestamp as a query parameter).  It turns out this feature worked before, and I just didn't realize it :).
+
+* Breaking Changes
+  * The `:allow_real_http => lambda { |uri| ... }` cassette option has been removed.  There was no way to get
+    this to work with the newly supported http libraries without extensive monkeypatching, and it was mostly
+    useful for localhost requests, which is more easily handled by the new `ignore_localhost` config setting.
+  * Removed methods and options that had been previously deprecated.  If you're upgrading from an old version,
+    I recommend upgrading to 0.4.1 first, deal with all the deprecation warnings, then upgrade to 1.0.0.
+
+* Misc Changes:
+  * Removed dependency on [jeweler](http://github.com/technicalpickles/jeweler).  Manage the gemspec by hand instead.
+  * Removed some extensions that are no longer necessary.
+
 ## 0.4.1 May 11, 2010
 * Fixed a bug: when `Net::HTTPResponse#read_body` was called after VCR had read the body to record a new request,
   it raised an error (`IOError: Net::HTTPResponse#read_body called twice`).  My fix extends Net::HTTPResponse

data/README.md

@@ -38,10 +38,25 @@ will replay the response from example.com when the http request is made.  This t
 made anymore), deterministic (the test will continue to pass, even if you are offline, or example.com goes down for
 maintenance) and accurate (the response from example.com will contain the same headers and body you get from a real request).
 
+## Features
+
+* Automatically records and replays your HTTP interactions with minimal setup/configuration code.
+* Supports multiple HTTP stubbing libraries.  Currently FakeWeb and WebMock are supported, and the adapter interface
+  is easy to implement for any future libraries.
+* Supports multiple HTTP libraries: [Net::HTTP](http://www.ruby-doc.org/stdlib/libdoc/net/http/rdoc/index.html)
+  (all HTTP stubbing libraries), [Patron](http://github.com/toland/patron) (WebMock only),
+  [HTTPClient](http://github.com/nahi/httpclient) (WebMock only) and
+  [em-http-request](http://github.com/igrigorik/em-http-request) (WebMock only).
+* The same request can receive different responses in different tests--just use different cassettes.
+* The recorded requests and responses are stored on disk as YAML and can easily be inspected and edited.
+* Dynamic responses are supported using ERB.
+* Disables all HTTP requests that you don't explicitly allow.
+* Simple cucumber integration is provided using tags.
+
 ## Cassettes
 
-Cassettes are the medium to which VCR records HTTP interactions, and the medium from which it replays them.  
-While a cassette is in use, new HTTP requests (or "new episodes", as VCR calls them) either get 
+Cassettes are the medium to which VCR records HTTP interactions, and the medium from which it replays them.
+While a cassette is in use, new HTTP requests (or "new episodes", as VCR calls them) either get
 recorded, or an error will be raised, depending on the cassette's `:record` mode (see below).  When you use
 a cassette that contains previously recorded HTTP interactions, it registers them with the http stubbing
 library of your choice (fakeweb or webmock) so that HTTP requests get the recorded response.  Between test
@@ -50,19 +65,7 @@ runs, cassettes are stored on disk as YAML files in your configured cassette lib
 Each cassette can be configured with a couple options:
 
 * `:record`: Specifies a record mode for this cassette.
-* `:allow_real_http`: You can use this to force VCR to always allow a real HTTP request for particular URIs.
-
-For example, to prevent the VCR cassette from recording and replaying requests to google.com, you could use:
-
-    lambda { |uri| uri.host == 'google.com' }
-
-All non-google requests would be recorded/replayed as normal.  You can also set this to `:localhost`,
-which is syntactic sugar for:
-
-    lambda { |uri| uri.host == 'localhost' }
-
-This is particularly useful for using VCR with [capybara](http://github.com/jnicklas/capybara)
-and any of its javascript drivers (see below for more info).
+* `:erb`: Used for dynamic cassettes (see below for more details).
 
 ## Record modes
 
@@ -80,6 +83,7 @@ and a per-cassette record mode when inserting a cassette.  The record modes are:
     VCR.config do |c|
       c.cassette_library_dir     = File.join(Rails.root, 'features', 'fixtures', 'cassette_library')
       c.http_stubbing_library    = :fakeweb
+      c.ignore_localhost         = true
       c.default_cassette_options = { :record => :none }
     end
 
@@ -92,7 +96,11 @@ configuration options:
   This is currently optional--VCR will try to guess based on the presence or absence of the `FakeWeb` or `WebMock`
   constants, but this is mostly done to assist users upgrading from VCR 0.3.1, which only worked with fakeweb and
   didn't have this option.  I recommend you explicitly configure this.
-* `default_cassette_options`: The default options for your cassettes.  These will be overriden by any options you
+* `ignore_localhost`: Defaults to false.  Setting it true does the following:
+    * Localhost requests will proceed as normal.  The "Real HTTP connections are disabled" error will not occur.
+    * Localhost requests will not be recorded.
+    * Previously recorded localhost requests will not be replayed.
+* `default_cassette_options`: The default options for your cassettes.  These will be overridden by any options you
   set on each individual cassette.
 
 ## Usage with your favorite ruby test/spec framework
@@ -147,8 +155,69 @@ If the last argument to `#tags` is a hash, VCR will use it as the options for th
 
 When you use any of the javascript-enabled drivers (selenium, celerity, culerity) with
 [capybara](http://github.com/jnicklas/capybara), it'll need to ping the app running on localhost.
-Set the `:allow_real_http => :localhost` option on your cassettes to allow this (or set it as a
-default cassette option in your configuration).
+Set the `ignore_localhost` option to true to allow this.
+
+## Cassette Customization
+
+Cassettes are stored as simple plain text YAML files and can easily be edited to suit your needs.  One common need
+is for a particular request to be stubbed using a regex rather than the raw URL.  This is handy for URLs that contain
+non-deterministic portions (such as timestamps)--since the URL will be a bit different each time, the URL from the
+recorded request will not match the URL for future requests.  You can simply change the URL to the YAML of the
+appropriate regex.
+
+Figure out the yaml in irb:
+
+    >> require 'yaml'
+    => true
+    >> puts /example\.com\/\d+/.to_yaml
+    --- !ruby/regexp /example\.com\/\d+/
+
+Edit your cassette file:
+
+    request: !ruby/struct:VCR::Request 
+      method: :get
+      uri: !ruby/regexp /example\.com\/\d+/
+      body: 
+      headers: 
+
+## Dynamic Cassettes
+
+VCR's default recording and replaying is static.  The exact response that is initially recorded will
+be replayed for all future requests.  Usually this is fine, but in some cases you need something more
+dynamic.  You can use [ERB](http://www.ruby-doc.org/stdlib/libdoc/erb/rdoc/) for this.
+
+Enable ERB evaluation of a cassette using the `:erb` option:
+
+    VCR.use_cassette('user-subscription', :erb => :true) do
+      # do something that makes an HTTP request
+    end
+
+You can use variables in your cassette's ERB by passing a hash:
+
+    VCR.use_cassette('user-subscription', :erb => { :user => User.last }) do
+      # do something that makes an HTTP request
+    end
+
+In your cassette:
+
+    request: !ruby/struct:VCR::Request 
+      method: :get
+      uri: http://some-domain.com:80/users/<%= user.id %>
+      body: 
+      headers: 
+      ...
+    response: !ruby/struct:VCR::Response 
+      ...
+      body: Hello, <%= user.name %>!
+
+## FakeWeb or WebMock?
+
+VCR works fine with either FakeWeb or WebMock.  Overall, WebMock has more features, and you'll need to use
+WebMock if you want to use VCR with an HTTP library besides `Net::HTTP`.  However, FakeWeb is currently
+about three times faster than WebMock, so you may want to stick with FakeWeb if you don't need WebMock's
+additional features.  You can see the
+[benchmarks](http://github.com/myronmarston/vcr/blob/master/benchmarks/http_stubbing_libraries.rb) for
+more details.
 
 ## Suggested Workflow
 
@@ -183,8 +252,7 @@ that it is making a new HTTP request, you'll be notified by an error as shown ab
 
 ## Ruby Version Compatibility
 
-VCR works on ruby [1.8.6](http://integrity186.heroku.com/vcr), [1.8.7](http://integrity187.heroku.com/vcr) and 
-[1.9.1](http://integrity191.heroku.com/vcr).
+VCR has been tested on ruby 1.8.6, 1.8.7 and 1.9.1.
 
 ## Notes, etc.
 
@@ -214,7 +282,7 @@ VCR works on ruby [1.8.6](http://integrity186.heroku.com/vcr), [1.8.7](http://in
 ## Thanks
 
 * [Aslak Hellesøy](http://github.com/aslakhellesoy) for [Cucumber](http://github.com/aslakhellesoy/cucumber).
-* [Bartosz Blimke](http://github.com/bblimke) for [WebMock](http://github.com/bblimke/webmock)
+* [Bartosz Blimke](http://github.com/bblimke) for [WebMock](http://github.com/bblimke/webmock).
 * [Chris Kampmeier](http://github.com/chrisk) for [FakeWeb](http://github.com/chrisk/fakeweb).
 * [Chris Young](http://github.com/chrisyoung) for [NetRecorder](http://github.com/chrisyoung/netrecorder),
   the inspiration for VCR.

data/lib/vcr.rb

@@ -3,15 +3,17 @@ require 'vcr/config'
 require 'vcr/cucumber_tags'
 require 'vcr/deprecations'
 require 'vcr/structs'
+require 'vcr/version'
 
 require 'vcr/extensions/net_http_response'
-require 'vcr/extensions/net_read_adapter'
 
 require 'vcr/http_stubbing_adapters/base'
 
 module VCR
   extend self
 
+  LOCALHOST_ALIASES = %w( localhost 127.0.0.1 )
+
   def current_cassette
     cassettes.last
   end
@@ -39,6 +41,7 @@ module VCR
     yield VCR::Config
     http_stubbing_adapter.check_version!
     http_stubbing_adapter.http_connections_allowed = false
+    http_stubbing_adapter.ignore_localhost = VCR::Config.ignore_localhost?
   end
 
   def cucumber_tags(&block)
@@ -57,6 +60,14 @@ module VCR
     end
   end
 
+  def record_http_interaction(interaction)
+    return unless cassette = current_cassette
+    return if http_stubbing_adapter.ignore_localhost? &&
+      LOCALHOST_ALIASES.include?(URI.parse(interaction.uri).host)
+
+    cassette.record_http_interaction(interaction)
+  end
+
   private
 
   def cassettes

data/lib/vcr/cassette.rb

@@ -1,18 +1,23 @@
 require 'fileutils'
 require 'yaml'
+require 'erb'
 
 module VCR
   class Cassette
+    class MissingERBVariableError < NameError; end
+
     VALID_RECORD_MODES = [:all, :none, :new_episodes].freeze
 
     attr_reader :name, :record_mode
 
     def initialize(name, options = {})
+      options = VCR::Config.default_cassette_options.merge(options)
+
       @name = name
-      @record_mode = options[:record] || VCR::Config.default_cassette_options[:record]
-      @allow_real_http_lambda = allow_real_http_lambda_for(options[:allow_real_http] || VCR::Config.default_cassette_options[:allow_real_http])
+      @record_mode = options[:record]
+      @erb = options[:erb]
 
-      deprecate_unregistered_record_mode
+      deprecate_old_cassette_options(options)
       raise_error_unless_valid_record_mode(record_mode)
 
       set_http_connections_allowed
@@ -23,6 +28,7 @@ module VCR
       write_recorded_interactions_to_disk
       VCR.http_stubbing_adapter.restore_stubs_checkpoint(name)
       restore_http_connections_allowed
+      restore_ignore_localhost_for_deprecation
     end
 
     def recorded_interactions
@@ -34,15 +40,15 @@ module VCR
     end
 
     def file
-      File.join(VCR::Config.cassette_library_dir, "#{name.to_s.gsub(/[^\w\-\/]+/, '_')}.yml") if VCR::Config.cassette_library_dir
-    end
-
-    def allow_real_http_requests_to?(uri)
-      @allow_real_http_lambda ? @allow_real_http_lambda.call(uri) : false
+      File.join(VCR::Config.cassette_library_dir, "#{sanitized_name}.yml") if VCR::Config.cassette_library_dir
     end
 
     private
 
+    def sanitized_name
+      name.to_s.gsub(/[^\w\-\/]+/, '_')
+    end
+
     def raise_error_unless_valid_record_mode(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}")
@@ -73,14 +79,18 @@ module VCR
 
       if file
         @original_recorded_interactions = begin
-          yaml_content = File.read(file)
-          YAML.load(yaml_content)
-        rescue TypeError
-          if yaml_content =~ /VCR::RecordedResponse/
-            raise "The VCR cassette #{name} 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."
-          else
-            raise
+          interactions = YAML.load(raw_yaml_content)
+
+          if VCR.http_stubbing_adapter.ignore_localhost?
+            interactions.reject! do |i|
+              i.uri.is_a?(String) && VCR::LOCALHOST_ALIASES.include?(URI.parse(i.uri).host)
+            end
           end
+
+          interactions
+        rescue TypeError
+          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 if File.exist?(file)
 
         recorded_interactions.replace(@original_recorded_interactions)
@@ -89,6 +99,31 @@ module VCR
       VCR.http_stubbing_adapter.stub_requests(recorded_interactions)
     end
 
+    def raw_yaml_content
+      content = File.read(file)
+      return content unless @erb
+
+      template = ERB.new(content)
+
+      begin
+        return template.result unless @erb.is_a?(Hash)
+
+        # create an object with methods for each desired local variable...
+        local_variables = Struct.new(*@erb.keys).new(*@erb.values)
+
+        # instance_eval seems to be the only way to get the binding for ruby 1.9: http://redmine.ruby-lang.org/issues/show/2161
+        template.result(local_variables.instance_eval { binding })
+      rescue NameError => e
+        var_name = e.message[/undefined local variable or method `(.*)' for/, 1].to_sym
+        example_hash = (@erb.is_a?(Hash) ? @erb : {}).merge(var_name => 'some value')
+
+        raise MissingERBVariableError.new(
+          "The ERB in the #{sanitized_name}.yml cassette file references undefined variable #{var_name}.  " +
+          "Pass it to the cassette using :erb => #{ example_hash.inspect }."
+        )
+      end
+    end
+
     def write_recorded_interactions_to_disk
       if VCR::Config.cassette_library_dir && new_recorded_interactions.size > 0
         directory = File.dirname(file)
@@ -96,17 +131,5 @@ module VCR
         File.open(file, 'w') { |f| f.write recorded_interactions.to_yaml }
       end
     end
-
-    def unstub_requests
-      VCR.http_stubbing_adapter.unstub_requests(@original_recorded_interactions)
-    end
-
-    def allow_real_http_lambda_for(allow_option)
-      if allow_option == :localhost
-        lambda { |uri| uri.host == 'localhost' }
-      else
-        allow_option
-      end
-    end
   end
 end

data/lib/vcr/config.rb

@@ -21,6 +21,15 @@ module VCR
           defined_constants[0].to_s.downcase.to_sym if defined_constants.size == 1
         end
       end
+
+      def ignore_localhost=(value)
+        VCR.http_stubbing_adapter && VCR.http_stubbing_adapter.ignore_localhost = value
+        @ignore_localhost = value
+      end
+
+      def ignore_localhost?
+        VCR.http_stubbing_adapter ? VCR.http_stubbing_adapter.ignore_localhost? : @ignore_localhost
+      end
     end
   end
 end

data/lib/vcr/deprecations.rb

@@ -1,54 +1,27 @@
 module VCR
-  def create_cassette!(*args)
-    warn "WARNING: VCR.create_cassette! is deprecated.  Instead, use: VCR.insert_cassette."
-    insert_cassette(*args)
-  end
-
-  def destroy_cassette!(*args)
-    warn "WARNING: VCR.destroy_cassette! is deprecated.  Instead, use: VCR.eject_cassette."
-    eject_cassette(*args)
-  end
-
-  def with_cassette(*args, &block)
-    warn "WARNING: VCR.with_cassette is deprecated.  Instead, use: VCR.use_cassette."
-    use_cassette(*args, &block)
-  end
-
   class Cassette
-    def destroy!(*args)
-      warn "WARNING: VCR::Cassette#destroy! is deprecated.  Instead, use: VCR::Cassette#eject."
-      eject(*args)
-    end
-
-    def cache_file(*args)
-      warn "WARNING: VCR::Cassette#cache_file is deprecated.  Instead, use: VCR::Cassette#file."
-      file(*args)
+    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.http_stubbing_adapter.ignore_localhost? && VCR::LOCALHOST_ALIASES.include?(uri.host)
     end
 
     private
 
-    def deprecate_unregistered_record_mode
-      if @record_mode == :unregistered
-        @record_mode = :new_episodes
-        Kernel.warn "WARNING: VCR's :unregistered record mode is deprecated.  Instead, use: :new_episodes."
+    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_ignore_localhost = VCR.http_stubbing_adapter.ignore_localhost?
+        VCR.http_stubbing_adapter.ignore_localhost = true
+        Kernel.warn "WARNING: #{message}"
+      elsif options[:allow_real_http]
+        raise ArgumentError.new(message)
       end
     end
-  end
-
-  class Config
-    def self.cache_dir(*args)
-      warn "WARNING: VCR::Config.cache_dir is deprecated.  Instead, use: VCR::Config.cassette_library_dir."
-      cassette_library_dir(*args)
-    end
 
-    def self.cache_dir=(value)
-      warn "WARNING: VCR::Config.cache_dir= is deprecated.  Instead, use: VCR::Config.cassette_library_dir=."
-      self.cassette_library_dir = value
-    end
-
-    def self.default_cassette_record_mode=(value)
-      warn %Q{WARNING: #default_cassette_record_mode is deprecated.  Instead, use: "default_cassette_options = { :record => :#{value.to_s} }"}
-      default_cassette_options.merge!(:record => value)
+    def restore_ignore_localhost_for_deprecation
+      if defined?(@original_ignore_localhost)
+        VCR.http_stubbing_adapter.ignore_localhost = @original_ignore_localhost
+      end
     end
   end
 end