Upgrade

See the 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:

VCR.config do |c|
  c.cassette_library_dir = 'cassettes'
  c.stub_with :fakeweb, :typhoeus
end

This will continue to work in VCR 2.0 but will generate deprecation warnings. Instead, you should change this to:

VCR.configure do |c|
  c.cassette_library_dir = 'cassettes'
  c.hook_into :fakeweb, :typhoeus
end

New Cassette Format

The cassette format has changed between VCR 1.x and VCR 2.0. VCR 1.x cassettes cannot be used with VCR 2.0.

The easiest way to upgrade is to simply delete your cassettes and re-record all of them. VCR also provides a rake task that attempts to upgrade your 1.x cassettes to the new 2.0 format. To use it, add the following line to your Rakefile:

load 'vcr/tasks/vcr.rake'

Then run rake vcr:migrate_cassettes DIR=path/to/your/cassettes/directory to upgrade your cassettes. Note that this rake task may be unable to upgrade some cassettes that make extensive use of ERB. In addition, now 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 you to register custom request matchers:

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

You can also pass any callable (an object that responds to #call, such as a lambda) to the :match_requests_on option:

port_matcher = lambda do |request_1, request_2|
  URI(request_1.uri).port == URI(request_2.uri).port
end

VCR.use_cassette("example", :match_requests_on => [:host, port_matcher, :method]) do
  # make an HTTP request
end

In addition, a helper method is provided for generating a custom matcher that ignores one or more query parameters:

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. Custom serializers must implement #file_extension, #serialize and #deserialize:

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] = 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:

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
  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

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.

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:

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:

VCR.configure do |c|
  c.debug_logger = File.open('log/vcr.log', 'w')
  # 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.

In VCR 1.x, request matching was delegated to the HTTP stubbing library (typically FakeWeb or WebMock). They contain some normalization logic that can treat some URIs that are different strings as equivalent. For example, WebMock ignores the ordering of query parameters:

> require 'webmock'
 => true
> uri1 = "http://foo.com/bar?a=1&b=2"
 => "http://foo.com/bar?a=1&b=2"
> uri2 = "http://foo.com/bar?b=2&a=1"
 => "http://foo.com/bar?b=2&a=1"
> uri1 == uri2
 => false
> WebMock::Util::URI.normalize_uri(uri1) == WebMock::Util::URI.normalize_uri(uri2)
 => true

VCR 2, the :uri matcher simply uses string equality. This means that there are some cases of non-deterministic URIs that VCR 1.x matched but VCR 2.0 will not match. If you need the :uri matcher to be tolerant of slight variations like these, you can easily override it:

VCR.configure do |c|
  c.register_request_matcher(:uri) do |r1, r2|
    WebMock::Util::URI.normalize_uri(r1.uri) == WebMock::Util::URI.normalize_uri(r2.uri)
  end
end

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:

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