vcr 2.0.0.rc1 → 2.0.0.rc2

data/.gitignore

@@ -35,3 +35,5 @@ features/Upgrade.md
 features/CONTRIBUTING.md
 
 .rvmrc
+.yardoc
+doc

data/.limited_red

@@ -0,0 +1 @@
+project name: vcr

data/.travis.yml

@@ -1,3 +1,4 @@
+language: ruby
 env: CUCUMBER_FORMAT=progress
 bundler_args: --without extras
 script: "bundle exec rake ci:build --trace"
@@ -6,10 +7,18 @@ rvm:
   - 1.9.2
   - 1.9.3
   - ree
-  - jruby
+  - jruby-18mode
+  - jruby-19mode
+  - rbx-18mode
+  - rbx-19mode
 branches:
   only:
     - master
     - 1-x-stable
     - travis-testing
+matrix:
+  allow_failures:
+    - rvm: jruby-19mode
+    - rvm: rbx-18mode
+    - rvm: rbx-19mode
 

data/.yardopts

@@ -0,0 +1,9 @@
+--no-private
+--exclude features
+--markup markdown
+--hide-void-return
+-
+CHANGELOG.md
+CONTRIBUTING.md
+LICENSE
+Upgrade.md

data/CHANGELOG.md

@@ -1,6 +1,56 @@
 ## In git
 
-[Full Changelog](http://github.com/myronmarston/vcr/compare/v2.0.0.rc1...master)
+[Full Changelog](http://github.com/myronmarston/vcr/compare/v2.0.0.rc2...master)
+
+## 2.0.0 RC 2 (February 23, 2012)
+
+[Full Changelog](http://github.com/myronmarston/vcr/compare/v2.0.0.rc1...v2.0.0.rc2)
+
+## New Features
+
+  * Add YARD documentation for the public API. Thanks to
+    [Ben Oakes](https://github.com/benjaminoakes) for help with setting
+    this up.
+  * Fix `around_http_request` hook so that `request.proceed` returns
+    the response.
+  * Resolve `cassette_library_dir` to an absolute path. Thanks to
+    [Nate Clark](https://github.com/heythisisnate) for the suggestion.
+  * Add to the `VCR::Request` API in `before_http_request` and
+    `after_http_request` hooks so the request has query methods like
+    `#real?`, `#recordable?`, `#ignored?`, etc. Thanks to
+    [Nate Clark](https://github.com/heythisisnate) for the idea.
+  * Allow filters (objects that respond to `#to_proc`) to be passed
+    to `before_http_request` and `after_http_request`.  This allows
+    an API like `before_http_request(:real?)` or
+    `after_http_request(lambda { |req| req.uri =~ /amazon/ })`.
+  * Add `debug_logger` config option. This can be used to
+    troubleshoot what VCR is doing.
+  * Update WebMock to version (1.8.0) that supports Excon stubbing.
+  * Store the encoding with the request & response bodies in the
+    serialized cassette.
+  * Add new `preserve_exact_body_bytes` option that base64 encodes the
+    request or response body in order to preserve the bytes exactly.
+    Thanks to [Jeff Pollard](https://github.com/Fluxx) for help
+    designing this feature and for code reviewing it.
+  * Update to and require latest Excon (0.9.6).
+
+## Bug Fixes
+
+  * Fix rspec metadata integration to allow the cassette name to be set
+    at the example group level and apply to multiple examples. Thanks to
+    [Paul Russell](https://github.com/pauljamesrussell) for reporting the
+    bug.
+  * Add missing `require 'vcr/version'` to the cassette migrator task.
+    If you tried the migration rake task with 2.0.0.rc1 and got a
+    `NoMethodError`, it should be fixed now.
+  * Update Excon dependency to 0.9.5; 0.9.5 includes an important bug
+    fix needed by VCR.
+  * Ensure the excon retry limit is honored properly.
+  * Ensure that the correct error class is raised by excon when stubbing
+    an unexpected status.
+  * Fix FakeWeb library hook so that it records the request body when
+    using `Net::HTTP.post_form`. Thanks to
+    [Retistic](https://github.com/Retistic) for reporting the bug.
 
 ## 2.0.0 RC 1 (December 8, 2011)
 

data/Gemfile

@@ -7,6 +7,8 @@ group :development do
   end
 end
 
+gem 'yard'
+
 # Additional gems that are useful, but not required for development.
 group :extras do
   gem 'guard-rspec'
@@ -15,8 +17,10 @@ group :extras do
   gem 'fuubar'
   gem 'fuubar-cucumber'
 
+  gem 'redcarpet', '~> 1.17.2'
+  gem 'github-markup'
+
   platforms :mri do
-    gem 'rcov'
     gem 'rb-fsevent'
   end
 

data/LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2010-2011 Myron Marston
+Copyright (c) 2010-2012 Myron Marston
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/README.md

@@ -52,17 +52,19 @@ maintenance) and accurate (the response will contain the same headers and body y
   * [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.
+* Request matching is configurable based on HTTP method, URI, host, path, body and headers, or you can easily
+  implement a custom request matcher to handle any need.
 * 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.
+* The recorded requests and responses are stored on disk in a serialization format of your choice
+  (currently YAML and JSON are built in, and you can easily implement your own custom serializer)
+  and can easily be inspected and edited.
 * Dynamic responses are supported using ERB.
 * 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.
+* Includes convenient RSpec macro and integration with RSpec 2 metadata.
 * 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.
 * Includes Rack and Faraday middleware.
 
 ## Usage
@@ -87,28 +89,8 @@ VCR has been tested on the following ruby interpreters:
 * MRI 1.8.7
 * 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.
+* JRuby
+* Rubinius
 
 ## Development
 
@@ -119,6 +101,12 @@ VCR has been tested on the following ruby interpreters:
   and create a topic branch for every separate change you make.
 * See the [Contributing](https://github.com/myronmarston/vcr/blob/master/CONTRIBUTING.md)
   guide for instructions on running the specs and features.
+* Documentation is generated with [YARD](http://yardoc.org/) ([cheat sheet](http://cheat.errtheblog.com/s/yard/)).
+  To generate while developing:
+
+```
+yard server --reload
+```
 
 If you find VCR useful, please recommend me on [working with rails](http://workingwithrails.com/person/16590-myron-marston).
 
@@ -139,13 +127,16 @@ Thanks also to the following people who have contributed patches or helpful sugg
 * [Aaron Brethorst](http://github.com/aaronbrethorst)
 * [Avdi Grimm](https://github.com/avdi)
 * [Bartosz Blimke](http://github.com/bblimke)
+* [Benjamin Oakes](https://github.com/benjaminoakes)
 * [Ben Hutton](http://github.com/benhutton)
 * [Bradley Isotope](https://github.com/bradleyisotope)
 * [Carlos Kirkconnell](https://github.com/kirkconnell)
 * [Eric Allam](http://github.com/rubymaverick)
 * [Flaviu Simihaian](https://github.com/closedbracket)
+* [Jeff Pollard](https://github.com/Fluxx)
 * [Justin Smestad](https://github.com/jsmestad)
 * [Karl Baum](https://github.com/kbaum)
+* [Michael Lavrisha](https://github.com/vrish88)
 * [Nathaniel Bibler](https://github.com/nbibler)
 * [Oliver Searle-Barnes](https://github.com/opsb)
 * [Paco Guzmán](https://github.com/pacoguzman)
@@ -156,11 +147,15 @@ Thanks also to the following people who have contributed patches or helpful sugg
 ## Similar Libraries
 
 * [Betamax](https://github.com/robfletcher/betamax) (Groovy)
-* [Ephemeral Response](https://github.com/sandro/ephemeral_response) (Ruby)
+* [VCR.js](https://github.com/elcuervo/vcr.js) (JavaScript)
+* [TapeDeck.js](https://github.com/EndangeredMassa/TapeDeck.js) (JavaScript)
 * [Mimic](https://github.com/acoulton/mimic) (PHP/Kohana)
+* [Ephemeral Response](https://github.com/sandro/ephemeral_response) (Ruby)
+* [Net::HTTP Spy](http://github.com/martinbtt/net-http-spy) (Ruby)
 * [NetRecorder](https://github.com/chrisyoung/netrecorder) (Ruby)
 * [Stale Fish](https://github.com/jsmestad/stale_fish) (Ruby)
+* [WebFixtures](http://github.com/trydionel/web_fixtures) (Ruby)
 
 ## Copyright
 
-Copyright (c) 2010-2011 Myron Marston. See LICENSE for details.
+Copyright (c) 2010-2012 Myron Marston. See LICENSE for details.

data/Rakefile

@@ -18,21 +18,36 @@ RSpec::Core::RakeTask.new(:spec) do |t|
   t.rspec_opts = %w[--format progress] if (ENV['FULL_BUILD'] || !using_git)
 end
 
-desc "Run all examples using rcov"
-RSpec::Core::RakeTask.new :rcov => :cleanup_rcov_files do |t|
-  t.rcov = true
-  t.rcov_opts =  %[-Ilib -Ispec --exclude "spec/*,gems/*,ping,basic_object" --text-report --sort coverage --aggregate coverage.data]
-end
-
-task :cleanup_rcov_files do
-  rm_rf 'coverage.data'
-end
-
 require 'cucumber/rake/task'
 Cucumber::Rake::Task.new
 
 task :default => [:spec, :cucumber]
 
+desc "Ensures we keep up 100% YARD coverage"
+task :yard_coverage do
+  coverage_stats = `yard stats --list-undoc 2>&1`
+  if coverage_stats.include?('100.00% documented')
+    puts "Nice work! 100% documentation coverage"
+  else
+    puts coverage_stats
+    raise "Documentation coverage is less than 100%"
+  end
+end
+
+desc "Checks the spec coverage and fails if it is less than 100%"
+task :check_code_coverage do
+  if RUBY_VERSION < '1.9' || RUBY_ENGINE != 'ruby'
+    puts "Cannot check code coverage--simplecov is not supported on this platform"
+  else
+    percent = File.read("./coverage/coverage_percent.txt").to_f
+    if percent < 98.0
+      raise "Spec coverage was not high enough: #{percent.round(2)}%"
+    else
+      puts "Nice job! Spec coverage is still above 98%"
+    end
+  end
+end
+
 namespace :ci do
   desc "Sets things up for a ci build on travis-ci.org"
   task :setup do
@@ -51,7 +66,7 @@ namespace :ci do
   end
 
   desc "Run a ci build"
-  task :build => [:setup, :spec, :cucumber]
+  task :build => [:setup, :spec, :cucumber, :yard_coverage, :check_code_coverage]
 end
 
 def ensure_relish_doc_symlinked(filename)
@@ -107,9 +122,23 @@ end
 
 desc "Migrate cucumber cassettes"
 task :migrate_cucumber_cassettes do
-  sh "git checkout cb3559d6ffcb36cb823ae96a677e380e5b86ed80 -- features"
-  require 'vcr/cassette/migrator'
+  require 'vcr'
+  require 'ruby-debug'
+
+  VCR.configure do |c|
+    c.cassette_library_dir = 'tmp/migrate'
+    c.default_cassette_options = { :serialize_with => :syck }
+  end
+
+  # We want 2.0.0 in the cucumber cassettes instead of 2.0.0.rc1
+  def VCR.version
+    "2.0.0"
+  end
+
   Dir["features/**/*.feature"].each do |feature_file|
+    # The ERB cassettes can't be migrated automatically.
+    next if feature_file.include?('dynamic_erb')
+
     puts " - Migrating #{feature_file}"
     contents = File.read(feature_file)
 
@@ -120,15 +149,22 @@ task :migrate_cucumber_cassettes do
       cassette_yml = capture.gsub(/^#{indentation}/, '')
       new_yml = nil
 
-      Dir.mktmpdir do |dir|
-        file_name = "#{dir}/cassette.yml"
-        File.open(file_name, 'w') { |f| f.write(cassette_yml) }
-        VCR::Cassette::Migrator.new(dir, StringIO.new).migrate!
-        new_yml = File.read(file_name)
+      file_name = "tmp/migrate/cassette.yml"
+      File.open(file_name, 'w') { |f| f.write(cassette_yml) }
+      cassette = VCR::Cassette.new('cassette')
+
+      hash = begin
+        cassette.serializable_hash
+      rescue => e
+        puts "   Skipping #{capture[0, 80]}"
+        next
       end
 
+      new_yml = VCR::Cassette::Serializers::Syck.serialize(hash)
+
       new_yml.gsub!(/^/, indentation)
       new_yml << indentation
+      new_yml.gsub!(/^\s+\n(\s+response:)/, '\1')
       contents.gsub!(capture, new_yml)
     end
 
@@ -147,3 +183,12 @@ task :run_last_cuke do
   end
 end
 
+desc "Boot test app"
+task :boot_test_app do
+  require './spec/support/vcr_localhost_server'
+  require './spec/support/sinatra_app'
+  VCR::SinatraApp.boot
+  puts "Booted sinatra app on port: #{VCR::SinatraApp.port}"
+  loop { }
+  puts "Shutting down."
+end

data/Upgrade.md

@@ -1,6 +1,10 @@
 See the [Changelog](changelog) for a complete list of changes from VCR
 1.x to 2.0. This file simply lists the most pertinent ones to upgrading.
 
+## Supported Rubies
+
+Ruby 1.8.6 and 1.9.1 are no longer supported.
+
 ## Configuration Changes
 
 In VCR 1.x, your configuration block would be something like this:
@@ -43,3 +47,199 @@ that VCR 2.0 does less normalization then before, it may not be able to
 migrate the cassette perfectly. It's recommended that you delete and
 re-record your cassettes if you are able.
 
+## Custom Request Matchers
+
+VCR 2.0 allows any callable (an object that responds to #call, such as a lambda)
+to be used as a request matcher:
+
+``` ruby
+VCR.configure do |c|
+  c.register_request_matcher :port do |request_1, request_2|
+    URI(request_1.uri).port == URI(request_2.uri).port
+  end
+end
+```
+
+In addition, a helper method is provided for generating a custom
+matcher that ignores one or more query parameters:
+
+``` ruby
+uri_without_timestamp = VCR.request_matchers.uri_without_param(:timestamp)
+VCR.configure do |c|
+  c.register_request_matcher(:uri_without_timestamp, &uri_without_timestamp)
+end
+```
+
+## Custom Serializers
+
+VCR 2.0 supports multiple serializers. `:yaml`, `:json`, `:psych` and
+`:syck` are supported out of the box, and it's easy to implement your
+own:
+
+``` ruby
+VCR.use_cassette("example", :serialize_with => :json) do
+  # make an HTTP request
+end
+
+marshal_serializer = Object.new
+marshal_serializer.instance_eval do
+  def file_extension
+    "marsh"
+  end
+
+  def serialize(hash)
+    Marshal.dump(hash)
+  end
+
+  def deserialize(string)
+    Marshal.load(string)
+  end
+end
+
+VCR.configure do |c|
+  c.cassette_serializers[:marshal] = serializer
+  c.default_cassette_options = { :serialize_with => :marshal }
+end
+```
+
+## Request Hooks
+
+VCR 2.0 has new request hooks, allowing you to inject custom logic
+before an HTTP request, after an HTTP request, or around an HTTP
+request:
+
+``` ruby
+VCR.configure do |c|
+  c.before_http_request do |request|
+    # do something with the request
+  end
+
+  c.after_http_request do |request, response|
+    # do something with the request or response
+  end
+
+  # around_http_request only works on ruby 1.9
+  VCR.configure do |c|
+    c.around_http_request do |request|
+      uri = URI(request.uri)
+      if uri.host == 'api.geocoder.com'
+        # extract an address like "1700 E Pine St, Seattle, WA"
+        # from a query like "address=1700+E+Pine+St%2C+Seattle%2C+WA"
+        address = CGI.unescape(uri.query.split('=').last)
+        VCR.use_cassette("geocoding/#{address}", &request)
+      else
+        request.proceed
+      end
+    end
+  end
+end
+```
+
+## Ignore a Request Based on Anything
+
+You can now define what requests get ignored using a block. This
+gives you the flexibility to ignore a requets based on anything.
+
+``` ruby
+VCR.configure do |c|
+  c.ignore_request do |request|
+    uri = URI(request.uri)
+    uri.host == 'localhost' && uri.port == 7500
+  end
+end
+```
+
+## Integration with RSpec 2 Metadata
+
+VCR can integrate directly with RSpec metadata:
+
+``` ruby
+VCR.configure do |c|
+  c.configure_rspec_metadata!
+end
+
+RSpec.configure do |c|
+  # so we can use `:vcr` rather than `:vcr => true`;
+  # in RSpec 3 this will no longer be necessary.
+  c.treat_symbols_as_metadata_keys_with_true_values = true
+end
+
+# apply it to an example group
+describe MyAPIWrapper, :vcr do
+end
+
+describe MyAPIWrapper do
+  # apply it to an individual example
+  it "does something", :vcr do
+  end
+
+  # set some cassette options
+  it "does something", :vcr => { :record => :new_episodes } do
+  end
+
+  # override the cassette name
+  it "does something", :vcr => { :cassette_name => "something" } do
+  end
+end
+```
+
+## Improved Faraday Integration
+
+VCR 1.x integrated with Faraday but required that you insert
+`VCR::Middleware::Faraday` into your middleware stack and configure
+`stub_with :faraday`. VCR 2 now takes care of inserting itself
+into the Faraday middleware stack if you configure `hook_into :faraday`.
+
+## Improved Unhandled Error Messages
+
+When VCR is unsure how to handle a request, the error message now contains
+suggestions for how you can configure VCR or your test so it can handle
+the request.
+
+## Debug Logger
+
+VCR 2.0 has a new configuration option that will turn on a logging mode
+so you can get more insight into what VCR is doing, for troubleshooting
+purposes:
+
+``` ruby
+VCR.configure do |c|
+  c.debug_logger = File.open('log/vcr.log')
+  # or...
+  c.debug_logger = $stderr
+end
+```
+
+## Playback Changes
+
+In VCR 1.x, a single HTTP interaction could be played back multiple
+times. This was mostly due to how VCR was implemented using FakeWeb
+and WebMock, and was not really by design. It's more in keeping with
+the philosophy of VCR to record the entire sequence of HTTP interactions
+(including the duplicate requests). In VCR 2, each recorded HTTP
+interaction can only be played back once unless you use the new
+`:allow_playback_repeats` option.
+
+## Preserve Exact Body Bytes
+
+Sometimes the request or response body of an HTTP interaction cannot
+be serialized and deserialized properly. Usually this is due to the body
+having invalid UTF-8 bytes. This new option configures VCR to base64
+encode the body in order to preserve the bytes exactly. It can either
+be configured globally with a block, or set on individual cassettes:
+
+``` ruby
+VCR.configure do |c|
+  c.preserve_exact_body_bytes do |http_message|
+    http_message.body.encoding.name == 'ASCII-8BIT' ||
+    !http_message.body.valid_encoding?
+  end
+end
+
+# or....
+
+VCR.use_cassette("my_cassette", :preserve_exact_body_bytes => true) do
+  # ...
+end
+```
+