VCR turns a Ruby test suite's HTTP traffic into YAML cassettes on disk
Record your test suite's HTTP interactions and replay them during future test runs for fast, deterministic, accurate tests.
At a glance
- What is it?
- The gem hooks into WebMock, Typhoeus, Faraday or Excon, writes each recorded request and response to a cassette file, and replays it on later runs. Its weak spots are uneven client coverage, cassettes that keep passing long after a remote API changes, and a public request for more maintainers.
- Who is it for?
- VCR fits a Ruby suite that calls HTTP services whose responses change slowly, and it fits badly when you want the suite to notice a live API drifting underneath it. Before adopting it, check three things: whether your HTTP client is on the supported list, whether your Rails app can keep cassettes out of test/fixtures, and who filters secrets before the first cassette gets committed.
- Can I use it commercially?
- Check first. The repository uses a licence we do not classify automatically, so read its LICENSE file before any commercial use.
- Is it still maintained?
- Yes. The repository last received commits 4 days ago.
- What is it written in?
- Mainly Ruby, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.
Star history
- vcr/vcr6,082 ★ · +6
| Repository | 2026-09-23 | 2026-11-15 |
|---|---|---|
| vcr/vcr | 6.1k | 6.1k |
6 Stars in the last 53 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
Two config calls decide where the cassette lands and which library intercepts HTTP
The whole setup is one configure block in a `spec_helper.rb` file: three requires, a `cassette_library_dir`, and a `hook_into` name. The hook picks the stubbing facility that does the intercepting, and the four names given are WebMock, Typhoeus, Faraday and Excon. Wrapping the code under test in `VCR.use_cassette` then puts everything HTTP inside that block under VCR's control.
require 'rubygems'
require 'test/unit'
require 'vcr'
VCR.configure do |config|
config.cassette_library_dir = "fixtures/vcr_cassettes"
config.hook_into :webmock
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
endThe cassette name becomes the file name. Run the test once and the request to iana.org is written to `fixtures/vcr_cassettes/synopsis.yml`. Run it again and no socket is opened at all. Point `cassette_library_dir` at `test/vcr_cassettes` instead if you want the files somewhere else.
Cassettes are YAML or JSON on disk, meant to be opened and edited
YAML and JSON are built in, and a custom serializer is something you write yourself. That choice matters more than it sounds. The file is the contract between one recorded run and every future run, and it is plain enough to read, diff and correct by hand when a stored value is wrong. One request can get different responses in different tests by sitting in different cassettes, so a fix to a recorded value never has to be global.
Responses that must be computed instead of frozen can come from ERB, which keeps a cassette from having to hold one hardcoded answer forever.
The repository layout backs this up. `features/` holds the Cucumber suite that doubles as the usage documentation, `spec/` holds the RSpec specs, and `docs/` sits next to both.
Matching keys off method, URI, host, path, body and headers
A replay has to decide which stored response belongs to the request happening now. The configurable matchers work on HTTP method, URI, host, path, body and headers, and when none of those cuts it you can implement a custom request matcher for whatever rule you need.
The other side of that same mechanism is blocking. VCR disables every HTTP request you have not explicitly allowed, so code that suddenly reaches for a new host fails instead of quietly passing through to the network.
A stale cassette keeps passing until you ask for re-recording
The trade is stated plainly in the quick example: replay the stored response and the test is fast and deterministic, and it keeps passing even if you are offline or iana.org goes down for maintenance. Nothing in that chain tells you the remote service changed shape. A cassette recorded against an old response format will hand back the old body long after the service stopped sending it, and the suite stays green while testing a fiction.
The feature list offers the remedy, re-recording cassettes on a configurable regular interval. The quick configure block does not name the setting that switches it on, so this is a documentation lookup rather than a config line you can copy.
Sensitive data has to be filtered before it reaches the cassette file
Cassettes hold response bodies verbatim, in a file that is meant to be committed. The README puts a note immediately after the quick example pointing at a Filter Sensitive Data page in the documentation, and the feature list includes filtering sensitive data from the response body. No snippet for it appears in the quick example, so a team whose responses carry tokens or personal data has to find that page before the first recording lands, not after.
Recorded responses contain the same headers and body you get from a real request, so headers end up in the file too. Matching on them and shipping them are two separate decisions, and the second one is yours.
Curb stops at Curl::Easy, and Typhoeus skips Easy and Multi
Client coverage is uneven in checkable ways. Curb is supported only for `Curl::Easy` at the moment. Typhoeus works through `Typhoeus::Hydra`, but not `Typhoeus::Easy` or `Typhoeus::Multi`. Patron, Curb, HTTPClient, em-http-request and Net::HTTP all require WebMock as the hooking library, while Excon and Faraday stand on their own. Anything built on Net::HTTP is covered by that same entry, and Mechanize, HTTParty and Rest Client are named as examples.
If your suite reaches a C client through a wrapper the list does not mention, this is where the plan breaks. For other languages the README points at Betamax and VCR.py, both Python, which are ports rather than drop-in answers for a Ruby suite.
test/fixtures is the one directory to avoid under Rails and Minitest
There is a single configuration trap named in the setup notes, and it belongs to Minitest: do not use `test/fixtures` as the cassette library directory when you are on Rails and Minitest, because Rails will transitively load any file in that directory as a model. Your YAML cassettes would then be read as models on every run, and the symptom would look like an autoload problem rather than a VCR problem.
The escape is simply to choose a different directory. The quick example uses `fixtures/vcr_cassettes`, which is not that path, and the same paragraph notes that a different library directory such as `test/vcr_cassettes` is allowed.
VCR 6.x tests MRI 2.7 through 4.0, and older Rubies stop at 6.1.0
The interpreter list for 6.x is MRI 4.0, 3.4, 3.3, 3.2, 3.1, 3.0 and 2.7. No other engine is named, so a JRuby or TruffleRuby shop is reading between the lines of the release notes rather than a compatibility table. The escape hatches are versioned: 6.0.0 is the last release supporting Ruby 2.3 and up, 6.1.0 the last supporting 2.6 and up, and upcoming releases will only explicitly support 2.7 and later.
Release policy is semantic versioning, with the public API defined by the API documentation. Patch releases carry bug fixes only, minor releases carry backward-compatible features, and only a major release may break the public API. That makes each minor bump something to read the CHANGELOG for.
Help Wanted, and sixteen months between v6.3.1 and v6.4.0
The README opens its Help Wanted note by saying it is looking for more maintainers, and invites people to spend time on pull requests, issues and discussions. The dates around it line up. Version 6.3.1 shipped on 2024-08-20 and v6.4.0 arrived on 2025-12-22, so about sixteen months separate them; v6.4.1 followed on 2026-10-30. The last push to the master branch was on 2026-10-30.
The tree is organized for contributors anyway: a CONTRIBUTING guide for running specs and features, DEVELOPMENT.md, CHANGELOG.md, Upgrade.md, a MAINTAINERS file and Code Climate metrics. Documentation is generated with YARD, and the command for that is one line:
yard server --reloadEditorial conclusion
VCR fits a Ruby suite that calls HTTP services whose responses change slowly, and it fits badly when you want the suite to notice a live API drifting underneath it. Before adopting it, check three things: whether your HTTP client is on the supported list, whether your Rails app can keep cassettes out of test/fixtures, and who filters secrets before the first cassette gets committed. Weigh the README's own request for more maintainers and the sixteen months between v6.3.1 and v6.4.0 against the API documentation at rubydoc.info.
Frequently asked questions
Which HTTP clients can the VCR gem record for?
It hooks into WebMock, Typhoeus, Faraday or Excon, and lists Patron, Curb, HTTPClient, em-http-request, Net::HTTP, Typhoeus, Excon and Faraday as supported clients, plus anything built on Net::HTTP such as Mechanize, HTTParty or Rest Client.
Where does a VCR cassette file get written?
It goes to the directory named by cassette_library_dir. The quick example uses fixtures/vcr_cassettes, so a cassette called synopsis becomes fixtures/vcr_cassettes/synopsis.yml, and test/vcr_cassettes is offered as another location.
Can VCR re-record cassettes on its own?
Yes, it can re-record cassettes on a configurable regular interval to keep them fresh. The quick configure block does not name that setting, so the interval option has to be looked up in the documentation.
How does VCR decide that a replayed request matches the recording?
Matching is configurable on HTTP method, URI, host, path, body and headers, and a custom request matcher can be implemented for anything else. One request can return different responses in different tests by using different cassettes.
Which Ruby versions does VCR 6 support?
VCR 6.x is tested on MRI 4.0, 3.4, 3.3, 3.2, 3.1, 3.0 and 2.7. VCR 6.0.0 is the last version supporting Ruby 2.3 and up, and 6.1.0 the last supporting 2.6 and up.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/vcr-vcr)Star history chart for your README
[](https://hysenlabs.com/projects/vcr-vcr)Was this useful?