17.1 Get your configuration

Use vcr_configuration() to get the current configuration

vcr_configuration()

#> <vcr configuration>
#>   Cassette Dir: .
#>   Record: once
#>   URI Parser: crul::url_parse
#>   Match Requests on: method, uri
#>   Preserve Bytes?: FALSE
#>   Logging?: FALSE
#>   ignored hosts: 
#>   ignore localhost?: FALSE
#>   Write disk path:

You can get the default configuration variables via vcr_config_defaults()

vcr_config_defaults()

#> $verbose_errors
#> [1] FALSE
#> 
#> $write_disk_path
#> NULL
#> 
#> $filter_sensitive_data
#> NULL
#> 
#> $log_opts
#> $log_opts$file
#> [1] "vcr.log"
#> 
#> $log_opts$log_prefix
#> [1] "Cassette"
#> 
#> $log_opts$date
#> [1] TRUE
#> 
#> 
#> $log
#> [1] FALSE
#> 
#> $linked_context
#> NULL
#> 
#> $cassettes
#> list()
#> 
#> $allow_http_connections_when_no_cassette
#> [1] FALSE
#> 
#> $clean_outdated_http_interactions
#> [1] FALSE
#> 
#> $re_record_interval
#> NULL
#> 
#> $turned_off
#> [1] FALSE
#> 
#> $preserve_exact_body_bytes
#> [1] FALSE
#> 
#> $uri_parser
#> [1] "crul::url_parse"
#> 
#> $ignore_request
#> NULL
#> 
#> $ignore_localhost
#> [1] FALSE
#> 
#> $ignore_hosts
#> NULL
#> 
#> $persist_with
#> [1] "FileSystem"
#> 
#> $serialize_with
#> [1] "yaml"
#> 
#> $allow_unused_http_interactions
#> [1] TRUE
#> 
#> $match_requests_on
#> [1] "method" "uri"   
#> 
#> $record
#> [1] "once"
#> 
#> $dir
#> [1] "."

These defaults are set when you load vcr - you can override any of them as described below.

17.2 Set configuration variables

Use vcr_configure() to set configuration variables.

For example, set a single variable:

vcr_configure(
  dir = "foobar/vcr_cassettes"
)

#> <vcr configuration>
#>   Cassette Dir: foobar/vcr_cassettes
#>   Record: once
#>   URI Parser: crul::url_parse
#>   Match Requests on: method, uri
#>   Preserve Bytes?: FALSE
#>   Logging?: FALSE
#>   ignored hosts: 
#>   ignore localhost?: FALSE
#>   Write disk path:

Or many at once:

vcr_configure(
  dir = "foobar/vcr_cassettes",
  record = "all"
)

#> <vcr configuration>
#>   Cassette Dir: foobar/vcr_cassettes
#>   Record: all
#>   URI Parser: crul::url_parse
#>   Match Requests on: method, uri
#>   Preserve Bytes?: FALSE
#>   Logging?: FALSE
#>   ignored hosts: 
#>   ignore localhost?: FALSE
#>   Write disk path:

17.3 Re-set to defaults

vcr_configure_reset()

17.4 dir - directory of where cassettes are stored

vcr_configure(dir = "new/path")

#> <vcr configuration>
#>   Cassette Dir: new/path
#>   Record: once
#>   URI Parser: crul::url_parse
#>   Match Requests on: method, uri
#>   Preserve Bytes?: FALSE
#>   Logging?: FALSE
#>   ignored hosts: 
#>   ignore localhost?: FALSE
#>   Write disk path:

17.5 record - record mode

One of: ‘all,’ ‘none,’ ‘new_episodes,’ ‘once.’ See ?recording for info on the options

vcr_configure(record = "new_episodes")

#> <vcr configuration>
#>   Cassette Dir: new/path
#>   Record: new_episodes
#>   URI Parser: crul::url_parse
#>   Match Requests on: method, uri
#>   Preserve Bytes?: FALSE
#>   Logging?: FALSE
#>   ignored hosts: 
#>   ignore localhost?: FALSE
#>   Write disk path:

17.6 match_requests_on - customize how vcr matches requests

vcr_configure(match_requests_on = c('query', 'headers'))

#> <vcr configuration>
#>   Cassette Dir: new/path
#>   Record: new_episodes
#>   URI Parser: crul::url_parse
#>   Match Requests on: query, headers
#>   Preserve Bytes?: FALSE
#>   Logging?: FALSE
#>   ignored hosts: 
#>   ignore localhost?: FALSE
#>   Write disk path:

17.7 allow_unused_http_interactions - Allow HTTP connections when no cassette

Default is TRUE, and thus does not error when http interactions are unused. You can set to FALSE in which case vcr errors when a cassette is ejected and not all http interactions have been used.

vcr_configure(allow_unused_http_interactions = FALSE)

#> <vcr configuration>
#>   Cassette Dir: new/path
#>   Record: new_episodes
#>   URI Parser: crul::url_parse
#>   Match Requests on: query, headers
#>   Preserve Bytes?: FALSE
#>   Logging?: FALSE
#>   ignored hosts: 
#>   ignore localhost?: FALSE
#>   Write disk path:

17.8 serialize_with - which serializer to use

Right now the only option is yaml

vcr_configure(serialize_with = "yaml")

#> <vcr configuration>
#>   Cassette Dir: new/path
#>   Record: new_episodes
#>   URI Parser: crul::url_parse
#>   Match Requests on: query, headers
#>   Preserve Bytes?: FALSE
#>   Logging?: FALSE
#>   ignored hosts: 
#>   ignore localhost?: FALSE
#>   Write disk path:

17.9 persist_with - which persister to use

Right now the only option is FileSystem

vcr_configure(persist_with = "FileSystem")

#> <vcr configuration>
#>   Cassette Dir: new/path
#>   Record: new_episodes
#>   URI Parser: crul::url_parse
#>   Match Requests on: query, headers
#>   Preserve Bytes?: FALSE
#>   Logging?: FALSE
#>   ignored hosts: 
#>   ignore localhost?: FALSE
#>   Write disk path:

17.10 ignore requests

vcr_configure(ignore_hosts = "google.com")

#> <vcr configuration>
#>   Cassette Dir: new/path
#>   Record: new_episodes
#>   URI Parser: crul::url_parse
#>   Match Requests on: query, headers
#>   Preserve Bytes?: FALSE
#>   Logging?: FALSE
#>   ignored hosts: google.com
#>   ignore localhost?: FALSE
#>   Write disk path:

vcr_configure(ignore_localhost = TRUE)

#> <vcr configuration>
#>   Cassette Dir: new/path
#>   Record: new_episodes
#>   URI Parser: crul::url_parse
#>   Match Requests on: query, headers
#>   Preserve Bytes?: FALSE
#>   Logging?: FALSE
#>   ignored hosts: google.com
#>   ignore localhost?: TRUE
#>   Write disk path:

vcr_configure(ignore_request = function(x) x == 5)

#> <vcr configuration>
#>   Cassette Dir: new/path
#>   Record: new_episodes
#>   URI Parser: crul::url_parse
#>   Match Requests on: query, headers
#>   Preserve Bytes?: FALSE
#>   Logging?: FALSE
#>   ignored hosts: google.com
#>   ignore localhost?: TRUE
#>   Write disk path:

17.11 uri_parser - which uri parser to use

By default we use httr::parse_url, but you can use a different one. Remember to pass in the function quoted, and namespaced.

vcr_configure(uri_parser = "urltools::url_parse")

#> <vcr configuration>
#>   Cassette Dir: new/path
#>   Record: new_episodes
#>   URI Parser: urltools::url_parse
#>   Match Requests on: query, headers
#>   Preserve Bytes?: FALSE
#>   Logging?: FALSE
#>   ignored hosts: google.com
#>   ignore localhost?: TRUE
#>   Write disk path:

17.12 preserve_exact_body_bytes

Some HTTP servers are not well-behaved and respond with invalid data. Set preserve_exact_body_bytes to TRUE to base64 encode the result body in order to preserve the bytes exactly as-is. vcr does not do this by default, since base64-encoding the string removes the human readibility of the cassette.

vcr_configure(preserve_exact_body_bytes = TRUE)

#> <vcr configuration>
#>   Cassette Dir: new/path
#>   Record: new_episodes
#>   URI Parser: urltools::url_parse
#>   Match Requests on: query, headers
#>   Preserve Bytes?: TRUE
#>   Logging?: FALSE
#>   ignored hosts: google.com
#>   ignore localhost?: TRUE
#>   Write disk path:

17.13 allow_http_connections_when_no_cassette

Determines how vcr treats HTTP requests that are made when no cassette is in use. When TRUE, requests made when there is no vcr cassette in use will be allowed. When FALSE (default), an [UnhandledHTTPRequestError] error will be raised for any HTTP request made when there is no cassette in use

vcr_configure(allow_http_connections_when_no_cassette = TRUE)

#> <vcr configuration>
#>   Cassette Dir: new/path
#>   Record: new_episodes
#>   URI Parser: urltools::url_parse
#>   Match Requests on: query, headers
#>   Preserve Bytes?: TRUE
#>   Logging?: FALSE
#>   ignored hosts: google.com
#>   ignore localhost?: TRUE
#>   Write disk path:

17.14 write_disk_path

The path to write files to for any requests that write responses to disk. By default this parameter is NULL; if you don’t set this and you do http requests while using vcr, you’ll get an error that you need to set this config variable (or you may just get an invalid path error).

For testing a package, you’ll probably want this path to be in your tests/ directory, perhaps next to your cassettes directory, e.g., if your cassettes are in tests/fixtures, then put your files from requests that write to disk in tests/files. Note: in the below example, vcr_configure is run from within tests/testthat, so you set the paths relative to that location.

vcr_configure(dir = "../fixtures", write_disk_path = "../files")

#> <vcr configuration>
#>   Cassette Dir: ../fixtures
#>   Record: once
#>   URI Parser: crul::url_parse
#>   Match Requests on: method, uri
#>   Preserve Bytes?: FALSE
#>   Logging?: FALSE
#>   ignored hosts: 
#>   ignore localhost?: FALSE
#>   Write disk path: ../files

If you want to ignore these files in your installed package, add them to .Rinstignore. If you want these files ignored on build then add them to .Rbuildignore. However, adding these files to .Rbuildignore will make tests that depend on these files break because the files won’t be found; so you’ll likely have to skip the associated tests as well.