> For the complete documentation index, see [llms.txt](https://nicolasiensen.gitbook.io/vcr-documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://nicolasiensen.gitbook.io/vcr-documentation/usage-with-rspec-metadata.md).

# Usage with RSpec metadata

VCR provides easy integration with RSpec using metadata. To set this up, call `configure_rspec_metadata!` in your `VCR.configure` block.

Once you've done that, you can have an example group or example use VCR by passing `:vcr` as an additional argument after the description string. It will set the cassette name based on the example's full description.

You can override the cassette name by passing a string (`:vcr => 'my_cassette'`).

If you need to override the other options, you can pass a hash (`:vcr => { ... }`).

## Background ()

*Given* a file named "spec/spec\_helper.rb" with:

```
require 'vcr'

VCR.configure do |c|
  c.cassette_library_dir = 'spec/cassettes'
  c.hook_into :webmock
  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
```

*And* a previously recorded cassette file "spec/cassettes/Group/optionally\_raises\_an\_error.yml" with:

```
--- 
http_interactions: 
- request: 
    method: get
    uri: http://example.com/foo
    body: 
      encoding: UTF-8
      string: ""
    headers: {}
  response: 
    status: 
      code: 200
      message: OK
    headers: 
      Content-Length: 
      - "5"
    body: 
      encoding: UTF-8
      string: Hello
    http_version: "1.1"
  recorded_at: Tue, 01 Nov 2011 04:58:44 GMT
recorded_with: VCR 2.0.0
```

## Use `:vcr` metadata

*Given* a file named "spec/vcr\_example\_spec.rb" with:

```
$server = start_sinatra_app do
  get('/') { "Hello" }
end

def make_http_request
  Net::HTTP.get_response('localhost', '/', $server.port).body
end

require 'spec_helper'

describe "VCR example group metadata", :vcr do
  it 'records an http request' do
    expect(make_http_request).to eq('Hello')
  end

  it 'records another http request' do
    expect(make_http_request).to eq('Hello')
  end

  it 'records an http request with a custom file name', :vcr => 'my_cassette' do
    expect(make_http_request).to eql('Hello')
  end

  context 'in a nested example group' do
    it 'records another one' do
      expect(make_http_request).to eq('Hello')
    end
  end
end

describe "VCR example metadata" do
  it 'records an http request', :vcr do
    expect(make_http_request).to eq('Hello')
  end
end
```

*When* I run `rspec spec/vcr_example_spec.rb`

*Then* it should pass with "5 examples, 0 failures"

*And* the file "spec/cassettes/VCR\_example\_group\_metadata/records\_an\_http\_request.yml" should contain "Hello"

*And* the file "spec/cassettes/VCR\_example\_group\_metadata/records\_another\_http\_request.yml" should contain "Hello"

*And* the file "spec/cassettes/my\_cassette.yml" should contain "Hello"

*And* the file "spec/cassettes/VCR\_example\_group\_metadata/in\_a\_nested\_example\_group/records\_another\_one.yml" should contain "Hello"

*And* the file "spec/cassettes/VCR\_example\_metadata/records\_an\_http\_request.yml" should contain "Hello".

## `:allow_unused_http_interactions => false` causes a failure if there are unused interactions

*And* a file named "spec/vcr\_example\_spec.rb" with:

```
require 'spec_helper'

describe "Group", :vcr => { :allow_unused_http_interactions => false } do
  it 'optionally raises an error' do
    # don't fail
  end
end
```

*When* I run `rspec spec/vcr_example_spec.rb`

*Then* it should fail with an error like:

```
There are unused HTTP interactions left in the cassette:
  - [get http://example.com/foo] => [200 "Hello"]
```

## `:allow_unused_http_interactions => false` does not raise if the example already failed

*And* a file named "spec/vcr\_example\_spec.rb" with:

```
require 'spec_helper'

describe "Group", :vcr => { :allow_unused_http_interactions => false } do
  it 'optionally raises an error' do
    raise "boom"
  end
end
```

*When* I run `rspec spec/vcr_example_spec.rb`

*Then* it should fail with "boom"

*And* the output should not contain "There are unused HTTP interactions".

## Pass a hash to set the cassette options

*Given* a file named "spec/vcr\_example\_spec.rb" with:

```
require 'spec_helper'

vcr_options = { :cassette_name => "example", :record => :new_episodes }
describe "Using an options hash", :vcr => vcr_options do
  it 'uses the provided cassette name' do
    expect(VCR.current_cassette.name).to eq("example")
  end

  it 'sets the given options' do
    expect(VCR.current_cassette.record_mode).to eq(:new_episodes)
  end
end
```

*When* I run `rspec spec/vcr_example_spec.rb`

*Then* it should pass with "2 examples, 0 failures".