vcr 1.6.0 → 1.7.0

data/.gitignore

@@ -26,3 +26,8 @@ features/fixtures/vcr_cassettes/**/temp/
 .bundle
 tmp
 rerun.txt
+Gemfile.lock
+
+features/README.md
+features/CHANGELOG.md
+features/LICENSE

data/.travis.yml

@@ -0,0 +1 @@
+script: "rake ci:build"

data/CHANGELOG.md

@@ -2,7 +2,34 @@
 
 ## In git
 
-[Full Changelog](http://github.com/myronmarston/vcr/compare/v1.6.0...master)
+[Full Changelog](http://github.com/myronmarston/vcr/compare/v1.7.0...master)
+
+## 1.7.0 (March 1, 2011)
+
+[Full Changelog](http://github.com/myronmarston/vcr/compare/v1.6.0...v1.7.0)
+
+* Use Psych for YAML serialization/deserialization when it is available.
+  Syck, Ruby's old YAML engine, will remove whitespace from some
+  strings.  Bug reported by [Robert Poor](https://github.com/rdpoor).
+* Add new `:update_content_length_header` cassette option.  The option
+  will ensure the `content-length` header value matches the actual
+  response body length.
+* Add new `:once` record mode.  It operates like `:new_episodes` except
+  when the cassette file already exists, in which case it causes
+  new requests to raise an error.  Feature suggested by
+  [Jamie Cobbett](https://github.com/jamiecobbett).
+* Made `:once` the default record mode.
+* Add new `filter_sensitive_data` configuration option.  Feature
+  suggested by [Nathaniel Bibler](https://github.com/nbibler).
+* Commit to [Semantic Versioning](http://semver.org/).  The cucumber
+  features document the public API for the purposes of semver.
+* Add support for CI builds using [travis-ci](http://travis-ci.org/myronmarston/vcr).
+* Add support for running tests through `gem test vcr`.  Visit
+  [test.rubygems.org](http://test.rubygems.org/gems/vcr) to see
+  the results.
+* Fix cucumber support to use separate `Before` & `After` hooks rather than
+  a single `Around` hook because of a bug in cucumber that prevents
+  background steps from running within the `Around` hook.
 
 ## 1.6.0 (February 3, 2011)
 
@@ -20,7 +47,7 @@
 
 * Fix response and request serialization so that the headers are raw
   strings.  This fixes intermittent YAML seg faults for paperclip
-  uploads to S3.  But reported by [Rob Slifka](https://github.com/rslifka).
+  uploads to S3.  Bug reported by [Rob Slifka](https://github.com/rslifka).
 
 ## 1.5.0 (January 12, 2011)
 

data/Gemfile

@@ -4,9 +4,9 @@ gemspec
 group :development do
   # patron and em-http-request can't install on JRuby, so we have to limit their platform here.
   platforms :ruby do
-    gem 'patron',           '~> 0.4.6'
+    gem 'patron',           '0.4.9'
     gem 'em-http-request',  '~> 0.2.7'
-    gem 'curb',             '~> 0.7.8'
+    gem 'curb',             '0.7.8'
     gem 'typhoeus',         '~> 0.2.1'
   end
 
@@ -34,7 +34,7 @@ group :extras do
 
   platforms :mri_19 do
     gem 'ruby-debug19'
-    gem 'ruby-debug-base19', '0.11.23'
+    gem 'ruby-debug-base19', RUBY_VERSION == '1.9.1' ? '0.11.23' : '~> 0.11.24'
   end
 end
 

data/README.md

@@ -1,4 +1,4 @@
-# VCR
+# VCR [![Build Status](http://travis-ci.org/myronmarston/vcr.png)](http://travis-ci.org/myronmarston/vcr)
 
 Record your test suite's HTTP interactions and replay them during future test runs for fast, deterministic, accurate tests.
 
@@ -30,15 +30,20 @@ maintenance) and accurate (the response from example.com will contain the same h
 ## Features
 
 * Automatically records and replays your HTTP interactions with minimal setup/configuration code.
-* Supports multiple HTTP stubbing libraries.  Currently FakeWeb, WebMock, Typhoeus and Faraday
-  are supported.
+* Supports and works with the HTTP stubbing facilities of multiple libraries.  Currently, the
+  following are supported:
+  * FakeWeb
+  * WebMock
+  * Typhoeus
+  * Faraday
 * Supports multiple HTTP libraries:
-  * [Patron](http://github.com/toland/patron) (WebMock)
-  * [Curb](http://github.com/taf2/curb) (WebMock -- only supports Curb::Easy at the moment)
-  * [HTTPClient](http://github.com/nahi/httpclient) (WebMock)
-  * [em-http-request](http://github.com/igrigorik/em-http-request) (WebMock)
-  * [Net::HTTP](http://www.ruby-doc.org/stdlib/libdoc/net/http/rdoc/index.html) (FakeWeb and WebMock)
+  * [Patron](http://github.com/toland/patron) (when using WebMock)
+  * [Curb](http://github.com/taf2/curb) (when using WebMock -- only supports Curb::Easy at the moment)
+  * [HTTPClient](http://github.com/nahi/httpclient) (when using WebMock)
+  * [em-http-request](http://github.com/igrigorik/em-http-request) (when using WebMock)
+  * [Net::HTTP](http://www.ruby-doc.org/stdlib/libdoc/net/http/rdoc/index.html) (when using FakeWeb and WebMock)
   * [Typhoeus](https://github.com/pauldix/typhoeus) (Typhoeus::Hydra, but not Typhoeus::Easy or Typhoeus::Multi)
+  * [Faraday](https://github.com/technoweenie/faraday)
   * And of course any library built on Net::HTTP, such as [Mechanize](http://github.com/tenderlove/mechanize),
     [HTTParty](http://github.com/jnunemaker/httparty) or [Rest Client](http://github.com/archiloque/rest-client).
 * Request matching is configurable based on HTTP method, URI, host, path, body and headers.
@@ -48,6 +53,7 @@ maintenance) and accurate (the response from example.com will contain the same h
 * Automatically re-records cassettes on a configurable regular interval to keep them fresh and current.
 * Disables all HTTP requests that you don't explicitly allow.
 * Simple cucumber integration is provided using tags.
+* Includes convenient RSpec macro.
 * Known to work well with many popular ruby libraries including RSpec 1 & 2, Cucumber, Test::Unit,
   Capybara, Mechanize, Rest-Client and HTTParty.
 * Extensively tested on 7 different ruby interpretters.
@@ -55,13 +61,51 @@ maintenance) and accurate (the response from example.com will contain the same h
 
 ## Usage
 
-Browse the [cucumber features](http://relishapp.com/myronmarston/vcr) or visit
-the [wiki](http://github.com/myronmarston/vcr/wiki) for usage info and
-documentation.
+Browse the [documentation](http://relishapp.com/myronmarston/vcr) for usage info.
 
 The [VCR talk given at Philly.rb](http://philly-rb-vcr-talk.heroku.com/) also
 contains good usage info.
 
+## Release Policy
+
+VCR follows the principles of [semantic versioning](http://semver.org/).
+The [cucumber features](http://relishapp.com/myronmarston/vcr) define
+VCR's public API.  Patch level releases contain only bug fixes.  Minor
+releases contain backward-compatible new features.  Major new releases
+contain backwards-incompatible changes to the public API.
+
+## Ruby Interpreter Compatibility
+
+VCR has been tested on the following ruby interpreters:
+
+* MRI 1.8.6
+* MRI 1.8.7
+* MRI 1.9.1
+* MRI 1.9.2
+* REE 1.8.7
+* JRuby 1.5.6
+* Rubinius 1.2.1
+
+## Known Issues
+
+* VCR uses YAML to serialize the HTTP interactions to disk in a
+  human-readable, human-editable format.  Unfortunately there are bugs
+  in Syck, Ruby's default YAML engine, that cause it to modify strings
+  when serializing them.  It appears the the bug is limited to entire
+  lines of whitespace.  A string such as `"1\n \n2"` will get changed
+  to `"1\n\n2"` (see [this gist](https://gist.github.com/815754) for
+  example code).  In practice, this usually isn't so bad, but it can
+  occassionally cause problems, especially when the recorded
+  response includes a `content_length` header and you are using an
+  HTTP client that relies on this.  Mechanize will raise an `EOFError`
+  when the `content_length` header does not match the response body
+  length.  One solution is to use Psych, the new YAML engine included
+  in Ruby 1.9.  VCR attempts to use Psych if possible, but you may have
+  to [re-compile ruby 1.9](http://rhnh.net/2011/01/31/psych-yaml-in-ruby-1-9-2-with-rvm-and-snow-leopard-osx)
+  to use it.  See [this issue](https://github.com/myronmarston/vcr/issues#issue/43)
+  for more info.  You can also use the `:update_content_length_header`
+  cassette option to ensure the header has the correct value.
+
 ## Development
 
 * Source hosted on [GitHub](http://github.com/myronmarston/vcr).

data/Rakefile

@@ -1,13 +1,18 @@
-require 'bundler'
-require 'bundler/setup'
-Bundler::GemHelper.install_tasks
+using_git = File.exist?(File.expand_path('../.git/', __FILE__))
+
+if using_git
+  require 'bundler'
+  require 'bundler/setup'
+  Bundler::GemHelper.install_tasks
+end
 
 require 'rake'
 require "rspec/core/rake_task"
 
 RSpec::Core::RakeTask.new(:spec) do |t|
   t.verbose = false
-  t.rspec_opts = %w[--format progress] if ENV['FULL_BUILD']
+  t.skip_bundler = true unless using_git
+  t.rspec_opts = %w[--format progress] if (ENV['FULL_BUILD'] || !using_git)
 end
 
 desc "Run all examples using rcov"
@@ -25,8 +30,42 @@ Cucumber::Rake::Task.new
 
 task :default => [:spec, :cucumber]
 
+namespace :ci do
+  desc "Sets things up for a ci build on travis-ci.org"
+  task :setup do
+    sh "git submodule init"
+    sh "git submodule update"
+  end
+
+  RSpec::Core::RakeTask.new(:spec) do |t|
+    t.verbose = true
+    t.rspec_opts = %w[--format progress --backtrace]
+  end
+
+  desc "Run a ci build"
+  task :build => [:setup, :spec, :cucumber]
+end
+
+def ensure_relish_doc_symlinked(filename)
+  from = File.expand_path("../features/#{filename}", __FILE__)
+  to = File.expand_path("../#{filename}", __FILE__)
+
+  if File.symlink?(from)
+    return if File.readlink(from) == to
+
+    # delete the old symlink
+    File.unlink(from)
+  end
+
+  FileUtils.ln_s to, from
+end
+
 desc "Push cukes to relishapp using the relish-client-gem"
 task :relish do
+  %w[ README.md CHANGELOG.md LICENSE ].each do |file|
+    ensure_relish_doc_symlinked(file)
+  end
+
   require 'vcr/version'
   sh "relish versions:add myronmarston/vcr:#{VCR.version}"
   sh "relish push vcr:#{VCR.version}"
@@ -34,3 +73,5 @@ end
 
 task :release => :relish
 
+# For gem-test: http://gem-testers.org/
+task :test => :spec

data/features/.nav

@@ -1,10 +1,16 @@
+getting_started.md (Getting Started)
+CHANGELOG.md (Changelog)
+about_the_cucumber_features.md (About the Cucumber Features)
+LICENSE (License)
 - cassettes:
   - format.feature
   - no_cassette.feature
   - request_matching.feature
   - dynamic_erb.feature
   - automatic_re_recording.feature
+  - update_content_length_header.feature
 - record_modes:
+  - once.feature
   - new_episodes.feature
   - none.feature
   - all.feature

data/features/{README.md → about_the_cucumber_features.md}

@@ -1,4 +1,4 @@
-## VCR
+## About the Cucumber Features
 
 The cucumber features provided here demonstrate all of the major features of
 VCR.  These features are executable documentation for VCR.

data/features/cassettes/update_content_length_header.feature

@@ -0,0 +1,106 @@
+Feature: Update content_length header
+
+  When the `:update_content_length_header` option is set to a truthy value,
+  VCR will ensure that the `content-length` header will have the correct
+  value.  This is useful in several situations:
+
+    - When you manually edit the cassette file and change the resonse body
+      length.  You can use this option so you don't have to manually calculate
+      and update the body length.
+    - When you use ERB, the response body length may vary.  This will ensure
+      it is always correct.
+    - Syck, the default YAML engine for ruby 1.8 (and 1.9, unless you compile
+      it to use Psych), has a bug where it sometimes will remove some
+      whitespace strings when you serialize them.  This may cause the
+      `content-length` header to have the wrong value.
+
+  This is especially important when you use a client that checks the
+  `content-length` header.  Mechanize, for example, will raise an `EOFError`
+  when the header value does not match the actual body length.
+
+  Background:
+    Given 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/
+          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: 
+            - "11"
+          body: Hello <modified>
+          http_version: "1.1"
+      """
+    Given a file named "common_stuff.rb" with:
+      """
+      require 'vcr'
+
+      VCR.config do |c|
+        c.cassette_library_dir = 'cassettes'
+        c.stub_with :fakeweb
+      end
+
+      def make_request_and_print_results
+        response = Net::HTTP.get_response('example.com', '/')
+        puts "Body length: #{response.body.length}"
+        puts "Header value: #{response['content-length']}"
+      end
+      """
+
+  Scenario: Default :update_content_length_header setting
+    Given a file named "default.rb" with:
+      """
+      require 'common_stuff'
+
+      VCR.use_cassette('example', :record => :none) do
+        make_request_and_print_results
+      end
+      """
+    When I run "ruby default.rb"
+    Then the output should contain:
+      """
+      Body length: 16
+      Header value: 11
+      """
+
+  Scenario: :update_content_length_header => false
+    Given a file named "false.rb" with:
+      """
+      require 'common_stuff'
+
+      VCR.use_cassette('example', :record => :none, :update_content_length_header => false) do
+        make_request_and_print_results
+      end
+      """
+    When I run "ruby false.rb"
+    Then the output should contain:
+      """
+      Body length: 16
+      Header value: 11
+      """
+
+  Scenario: :update_content_length_header => true
+    Given a file named "true.rb" with:
+      """
+      require 'common_stuff'
+
+      VCR.use_cassette('example', :record => :none, :update_content_length_header => true) do
+        make_request_and_print_results
+      end
+      """
+    When I run "ruby true.rb"
+    Then the output should contain:
+      """
+      Body length: 16
+      Header value: 16
+      """
+

data/features/configuration/default_cassette_options.feature

@@ -21,7 +21,7 @@ Feature: default_cassette_options
       end
       """
 
-  Scenario: cassettes get default values from configured default_cassette_options
+  Scenario: cassettes get default values from configured `default_cassette_options`
     Given a file named "default_cassette_options.rb" with:
       """
       require 'vcr_setup.rb'
@@ -38,7 +38,7 @@ Feature: default_cassette_options
       ERB: true
       """
 
-  Scenario: :match_requests_on defaults to [:method, :uri] when it has not been set
+  Scenario: `:match_requests_on` defaults to `[:method, :uri]` when it has not been set
     Given a file named "default_cassette_options.rb" with:
       """
       require 'vcr_setup.rb'
@@ -50,6 +50,24 @@ Feature: default_cassette_options
     When I run "ruby default_cassette_options.rb"
     Then the output should contain "Match Requests On: [:method, :uri]"
 
+  Scenario: `:record` defaults to `:once` when it has not been set
+    Given a file named "default_record_mode.rb" with:
+      """
+      require 'vcr'
+
+      VCR.config do |c|
+        # not important for this example, but must be set to something
+        c.stub_with :webmock
+        c.cassette_library_dir = 'cassettes'
+      end
+
+      VCR.use_cassette('example') do
+        puts "Record mode: #{VCR.current_cassette.record_mode.inspect}"
+      end
+      """
+    When I run "ruby default_record_mode.rb"
+    Then the output should contain "Record mode: :once"
+
   Scenario: cassettes can set their own options
     Given a file named "default_cassette_options.rb" with:
       """

data/features/configuration/filter_sensitive_data.feature

@@ -0,0 +1,154 @@
+Feature: Filter sensitive data
+
+  The `filter_sensitive_data` configuration option can be used to prevent
+  sensitive data from being written to your cassette files.  This may be
+  important if you commit your cassettes files to source controla and do
+  not want your sensitive data exposed.  Pass the following arguments to
+  `filter_sensitive_data`:
+
+    - A substitution string.  This is the string that will be written to
+      the cassettte file as a placeholder.  It should be unique and you
+      may want to wrap it in special characters like `{ }` or `< >`.
+    - A symbol specifying a tag (optional).  If a tag is given, the
+      filtering will only be applied to cassettes with the given tag.
+    - A block.  The block should return the sensitive text that you want
+      replaced with the substitution string.  If your block accepts an
+      argument, the HTTP interaction will be yielded so that you can
+      dynamically specify the sensitive text based on the interaction
+      (see the last scenario for an example of this).
+
+  When the interactions are replayed, the sensitive text will replace the
+  substitution string so that the interaction will be identical to what was
+  originally recorded.
+
+  You can specify as many filterings as you want.
+
+  Scenario: Multiple filterings
+    Given a file named "filtering.rb" with:
+      """
+      require 'vcr_cucumber_helpers'
+
+      if ARGV.include?('--with-server')
+        start_sinatra_app(:port => 7777) do
+          get('/') { "Hello World" }
+        end
+      end
+
+      require 'vcr'
+
+      VCR.config do |c|
+        c.stub_with :fakeweb
+        c.cassette_library_dir = 'cassettes'
+        c.filter_sensitive_data('<GREETING>') { 'Hello' }
+        c.filter_sensitive_data('<LOCATION>') { 'World' }
+      end
+
+      VCR.use_cassette('filtering', :record => :new_episodes) do
+        response = Net::HTTP.get_response('localhost', '/', 7777)
+        puts "Response: #{response.body}"
+      end
+      """
+    When I run "ruby filtering.rb --with-server"
+    Then the output should contain "Response: Hello World"
+     And the file "cassettes/filtering.yml" should contain "body: <GREETING> <LOCATION>"
+     And the file "cassettes/filtering.yml" should not contain "Hello"
+     And the file "cassettes/filtering.yml" should not contain "World"
+
+    When I run "ruby filtering.rb"
+    Then the output should contain "Hello World"
+
+  Scenario: Filter tagged cassettes
+    Given a file named "tagged_filtering.rb" with:
+      """
+      require 'vcr_cucumber_helpers'
+
+      if ARGV.include?('--with-server')
+        response_count = 0
+        start_sinatra_app(:port => 7777) do
+          get('/') { "Hello World #{response_count += 1 }" }
+        end
+      end
+
+      require 'vcr'
+
+      VCR.config do |c|
+        c.stub_with :fakeweb
+        c.cassette_library_dir = 'cassettes'
+        c.filter_sensitive_data('<LOCATION>', :my_tag) { 'World' }
+      end
+
+      VCR.use_cassette('tagged', :tag => :my_tag, :record => :new_episodes) do
+        response = Net::HTTP.get_response('localhost', '/', 7777)
+        puts "Tagged Response: #{response.body}"
+      end
+
+      VCR.use_cassette('untagged', :record => :new_episodes) do
+        response = Net::HTTP.get_response('localhost', '/', 7777)
+        puts "Untagged Response: #{response.body}"
+      end
+      """
+    When I run "ruby tagged_filtering.rb --with-server"
+    Then the output should contain each of the following:
+      | Tagged Response: Hello World 1   |
+      | Untagged Response: Hello World 2 |
+     And the file "cassettes/tagged.yml" should contain "body: Hello <LOCATION> 1"
+     And the file "cassettes/untagged.yml" should contain "body: Hello World 2"
+
+    When I run "ruby tagged_filtering.rb"
+    Then the output should contain each of the following:
+      | Tagged Response: Hello World 1   |
+      | Untagged Response: Hello World 2 |
+
+  Scenario: Filter dynamic data based on yielded HTTP interaction
+    Given a file named "dynamic_filtering.rb" with:
+      """
+      require 'vcr_cucumber_helpers'
+      include_http_adapter_for('net/http')
+
+      if ARGV.include?('--with-server')
+        start_sinatra_app(:port => 7777) do
+          helpers do
+            def request_header_for(header_key_fragment)
+              key = env.keys.find { |k| k =~ /#{header_key_fragment}/i }
+              env[key]
+            end
+          end
+
+          get('/') { "#{request_header_for('username')}/#{request_header_for('password')}" }
+        end
+      end
+
+      require 'vcr'
+
+      USER_PASSWORDS = {
+        'john.doe' => 'monkey',
+        'jane.doe' => 'cheetah'
+      }
+
+      VCR.config do |c|
+        c.stub_with :webmock
+        c.cassette_library_dir = 'cassettes'
+        c.filter_sensitive_data('<PASSWORD>') do |interaction|
+          USER_PASSWORDS[interaction.request.headers['x-http-username'].first]
+        end
+      end
+
+      VCR.use_cassette('example', :record => :new_episodes, :match_requests_on => [:method, :uri, :headers]) do
+        puts "Response: " + response_body_for(
+          :get, 'http://localhost:7777/', nil,
+          'X-HTTP-USERNAME' => 'john.doe',
+          'X-HTTP-PASSWORD' => USER_PASSWORDS['john.doe']
+        )
+      end
+      """
+    When I run "ruby dynamic_filtering.rb --with-server"
+    Then the output should contain "john.doe/monkey"
+    And the file "cassettes/example.yml" should contain "body: john.doe/<PASSWORD>"
+    And the file "cassettes/example.yml" should contain a YAML fragment like:
+      """
+            x-http-password: 
+            - <PASSWORD>
+      """
+
+    When I run "ruby dynamic_filtering.rb"
+    Then the output should contain "john.doe/monkey"