Record your test suite's HTTP interactions and replay them during future test runs for fast, deterministic, accurate tests.
Ruby Gherkin Shell
Latest commit 2217f68 Jan 18, 2017 @ecnalyr ecnalyr committed on GitHub Merge pull request #632 from dentarg/patch-1
Fix typo in cucumber feature
Permalink
Failed to load latest commit information.
benchmarks Refactor logger. Sep 22, 2013
features Fix typo in cucumber feature Jan 18, 2017
lib allow non lantin characters in filename May 30, 2016
script script/ci.sh: use echo instead of printf if doc coverage test failed Dec 9, 2015
spec use kind_of for compatibility with ruby < 2.4 Jan 17, 2017
.gitignore Simplify testing with secondary Gemfiles Oct 6, 2015
.hound.yml Starting the use of hound-ci. Jan 6, 2015
.lgtm Change how we approve things Dec 21, 2015
.rspec Switch back to more compact RSpec output by default Oct 5, 2015
.travis.yml Allow rbx-2 to fail without breaking Travis build. Dec 7, 2016
.yardopts Add additional files to yard listing. Feb 13, 2012
Appraisals Test with Faraday 0.8 additionally in CI Oct 10, 2014
CHANGELOG.md bump version for rubygems issue May 22, 2016
CONTRIBUTING.md we use rspec 3 now Jan 2, 2016
Gemfile lock patron to version 0.6.3 to get the build passing Dec 5, 2016
Gemfile.cucumber-1.3 Test Cucumber integration with cucumber 1.3 version as well Oct 6, 2015
Gemfile.faraday-0.8 Avoid installing HTTP libraries with native extensions for non-MRI Oct 6, 2015
Gemfile.typhoeus-0.4 Simplify testing with secondary Gemfiles Oct 6, 2015
LICENSE The README needs badges, cleaning up Jan 3, 2015
MAINTAINERS We want to use LGTM.co for approval Dec 21, 2015
README.md Fix typo in README Jul 7, 2016
Rakefile Run RSpec and Cucumber suites by default. Dec 7, 2016
Upgrade.md Update upgrade doc, variable serializer does not exist [ci skip] Nov 16, 2015
cucumber.yml Globally set `--backtrace` flag for RSpec/Cucumber in CI Oct 11, 2014
vcr.gemspec remove test files from built gem Sep 6, 2016

README.md

vcr

Quality Coverage Build Dependencies Downloads Tags Releases Issues License Version OpenCollective OpenCollective

Record your test suite's HTTP interactions and replay them during future test runs for fast, deterministic, accurate tests.

Help Wanted

We're looking for new maintainers. If you'd like to help maintain a well-used gem please join the vcr-maintainers google group.

Usage

require 'rubygems'
require 'test/unit'
require 'vcr'

VCR.configure do |config|
  config.cassette_library_dir = "fixtures/vcr_cassettes"
  config.hook_into :webmock # or :fakeweb
end

class VCRTest < Test::Unit::TestCase
  def test_example_dot_com
    VCR.use_cassette("synopsis") do
      response = Net::HTTP.get_response(URI('http://www.iana.org/domains/reserved'))
      assert_match /Example domains/, response.body
    end
  end
end

Run this test once, and VCR will record the HTTP request to fixtures/vcr_cassettes/synopsis.yml. Run it again, and VCR will replay the response from iana.org when the HTTP request is made. This test is now fast (no real HTTP requests are made anymore), deterministic (the test will continue to pass, even if you are offline, or iana.org goes down for maintenance) and accurate (the response will contain the same headers and body you get from a real request). You can use a different cassette library directory (e.g., "test/vcr_cassettes").

Rails and Minitest: Do not use 'test/fixtures' as the directory if you're using Rails and Minitest (Rails will instead transitively load any files in that directory as models).

Features

  • Automatically records and replays your HTTP interactions with minimal setup/configuration code.
  • Supports and works with the HTTP stubbing facilities of multiple libraries. Currently, the following are supported:
  • Supports multiple HTTP libraries:
  • 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 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.
  • Optionally 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 macros 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.
  • Includes Rack and Faraday middleware.

The docs come in two flavors:

  • The relish docs contain example-based documentation (VCR's Cucumber suite, in fact). It's a good place to look when you are first getting started with VCR, or if you want to see an example of how to use a feature.
  • The rubydoc.info docs contain API documentation. The API docs contain detailed info about all of VCR's public API.
  • See the Upgrade doc for info about what's new and changed in VCR 2.0.

There is also a Railscast, which will get you up and running in no-time http://railscasts.com/episodes/291-testing-with-vcr.

Release Policy

VCR follows the principles of semantic versioning. The API documentation defines 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.9.3
  • MRI 2.0.0
  • MRI 2.1
  • MRI 2.2
  • MRI 2.3.0
  • JRuby
  • Rubinius

Note that as of VCR 3, 1.8.7 and 1.9.2 are not supported.

Development

  • Source hosted on GitHub.
  • Direct questions and discussions to the mailing list.
  • Report issues on GitHub Issues.
  • Pull requests are very welcome! Please include spec and/or feature coverage for every patch, and create a topic branch for every separate change you make.
  • See the Contributing guide for instructions on running the specs and features.
  • Code quality metrics are checked by Code Climate.
  • Documentation is generated with YARD (cheat sheet). To generate while developing:
yard server --reload

Ports in Other Languages

Related Projects

  • Mr. Video (Rails engine for managing VCR cassettes and episodes)

Similar Libraries in Ruby

Credits

Thanks also to the following people who have contributed patches or helpful suggestions:

Backers

Support us with a monthly donation and help us continue our activities. [Become a backer]

Sponsors

Become a sponsor and get your logo on our README on Github with a link to your site. [Become a sponsor]

Copyright

Copyright (c) 2010-2015 Myron Marston

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.