# Getting Started

## Install it

```bash
[sudo] gem install vcr
[sudo] gem install webmock
```

## Configure it

Create a file named `vcr_setup.rb` with content like:

```ruby
require 'vcr'

VCR.configure do |c|
  c.cassette_library_dir = 'vcr_cassettes'
  c.hook_into :webmock
end
```

Ensure this file is required by your test suite before any of the tests are run.

## Use it

Run your tests. Any tests that make HTTP requests using Net::HTTP will raise errors like:

```
================================================================================
An HTTP request has been made that VCR does not know how to handle:
  GET http://example.com/

There is currently no cassette in use. There are a few ways
you can configure VCR to handle this request:

  * If you want VCR to record this request and play it back during future test
    runs, you should wrap your test (or this portion of your test) in a
    `VCR.use_cassette` block [1].
  * If you only want VCR to handle requests made while a cassette is in use,
    configure `allow_http_connections_when_no_cassette = true`. VCR will
    ignore this request since it is made when there is no cassette [2].
  * If you want VCR to ignore this request (and others like it), you can
    set an `ignore_request` callback [3].

[1] https://www.relishapp.com/myronmarston/vcr/v/2-0-0/docs/getting-started
[2] https://www.relishapp.com/myronmarston/vcr/v/2-0-0/docs/configuration/allow-http-connections-when-no-cassette
[3] https://www.relishapp.com/myronmarston/vcr/v/2-0-0/docs/configuration/ignore-request
================================================================================
```

Find one of these tests (preferably one that uses the same HTTP method and request URL every time--if not, you'll have to configure the request matcher). Wrap the body of it (or at least the code that makes the HTTP request) in a `VCR.use_cassette` block:

```ruby
VCR.use_cassette('whatever cassette name you want') do
   # the body of the test would go here...
end
```

Run this test. It will record the HTTP request to disk as a cassette (a test fixture), with content like:

```yaml
http_interactions:
- request:
    method: get
    uri: http://example.com/
    body: ''
    headers: {}
  response:
    status:
      code: 200
      message: OK
    headers:
      Content-Type:
      - text/html;charset=utf-8
      Content-Length:
      - '26'
    body: This is the response body
    http_version: '1.1'
  recorded_at: Tue, 01 Nov 2011 04:58:44 GMT
recorded_with: VCR 2.0.0
```

Disconnect your computer from the internet. Run the test again. It should pass since VCR is automatically replaying the recorded response when the request is made.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://nicolasiensen.gitbook.io/vcr-documentation/master.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.