Skip to contents

Global Configuration Options

Source: R/configuration.R
vcr_configure.Rd

Configurable options that define vcr's default behavior.

Usage

vcr_configure(...)

local_vcr_configure(..., .frame = parent.frame())

vcr_configure_reset()

vcr_configuration()

vcr_config_defaults()

Arguments

...

configuration settings used to override defaults. See below for a complete list of valid arguments.

.frame

Attach exit handlers to this environment. Typically, this should be either the current environment or a parent frame (accessed through parent.frame()). See vignette("withr", package = "withr") for more details.

Configurable settings

vcr options

File locations

  • dir Cassette directory

  • write_disk_path (character) path to write files to for any requests that write responses to disk. By default this will be {cassette-name}-files/ inside the cassette directory.

Contexts

  • turned_off (logical) VCR is turned on by default. Default: FALSE

  • allow_unused_http_interactions (logical) Default: TRUE

Filtering

  • ignore_hosts (character) Vector of hosts to ignore. e.g., localhost, or google.com. These hosts are ignored and real HTTP requests are allowed to go through.

  • ignore_localhost (logical) Default: FALSE

  • ignore_request List of requests to ignore (feature not implemented yet).

  • filter_sensitive_data named list of values to replace. Format is:

    list(thing_to_replace_it_with = thing_to_replace)

    We replace all instances of thing_to_replace with thing_to_replace_it_with. Uses gsub() internally, with fixed=TRUE; so does exact matches. Before recording (writing to a cassette) we do the replacement and then when reading from the cassette we do the reverse replacement to get back to the real data. Before record replacement happens in internal function write_interactions(), while before playback replacement happens in internal function YAML$deserialize()

  • filter_sensitive_data_regex named list of values to replace. Follows filter_sensitive_data format, except uses fixed=FALSE in the gsub() function call; this means that the value in thing_to_replace is a regex pattern.

  • filter_request_headers (character/list) request headers to filter. A character vector of request headers to remove - the headers will not be recorded to disk. Alternatively, a named list similar to filter_sensitive_data instructing vcr with what value to replace the real value of the request header. Note that for the httr2 package only we redact request headers automatically that are marked (via attributes) as redacted.

  • filter_response_headers (character/list) response headers to filter. A character vector of response headers to remove - the headers will not be recorded to disk. Alternatively, a named list similar to filter_sensitive_data instructing vcr with what value to replace the real value of the response header.

  • filter_query_parameters (character/list) query parameters to filter. A character vector of query parameters to remove - the query parameters will not be recorded to disk. Alternatively, a named list similar to filter_sensitive_data instructing vcr with what value to replace the real value of the query parameter.

Errors

  • verbose_errors (logical) Controls verbosity of errors when cassette recording/usage fails. Default is FALSE (less verbose errors). If TRUE, error messages will include more details about what went wrong and suggest possible solutions. For testing in an interactive R session, if verbose_errors=FALSE, you can run vcr_last_error() to get the full error. If in non-interactive mode, which most users will be in when running the entire test suite for a package, you can set an environment variable (VCR_VERBOSE_ERRORS) to toggle this setting (e.g., Sys.setenv(VCR_VERBOSE_ERRORS=TRUE); devtools::test()).

Internals

  • cassettes (list) Internal use only.

  • linked_context (logical) Linked context.

Logging

See vcr_configure_log()

Cassette Options

These settings can be configured globally, using vcr_configure(), or locally, using either use_cassette() or insert_cassette(). Global settings are applied to all cassettes but are overridden by settings defined locally for individual cassettes.

  • record (character) One of 'all', 'none', 'new_episodes', or 'once'. See use_cassette() for details.

  • match_requests_on vector of matchers. Default: (method, uri) See use_cassette() for details.

  • serialize_with: (character) "yaml" or "json". Note that you can have multiple cassettes with the same name as long as they use different serializers; so if you only want one cassette for a given cassette name, make sure to not switch serializers, or clean up files you no longer need.

  • json_pretty: (logical) Should JSON be newline separated to be easier to read? If FALSE, remove newlines to save disk space. Default: FALSE.

  • preserve_exact_body_bytes (logical) Force a binary (base64) representation of the request and response bodies for binary content. By default, vcr will look at the Content-Type header to determine if this is necessary.

  • re_record_interval (numeric) When given, the cassette will be re-recorded at the given interval, in seconds.

  • clean_outdated_http_interactions (logical) Should outdated interactions be recorded back to file? Default: FALSE.

  • warn_on_empty_cassette (logical) Should a warning be thrown when an empty cassette is detected? Empty cassettes are cleaned up (deleted) either way. This option only determines whether a warning is thrown or not. Default: FALSE.

Examples

vcr_configure(dir = tempdir())
vcr_configure(dir = tempdir(), record = "all")
vcr_configuration()
#> <vcr configuration>
#>   Cassette Dir: /tmp/RtmpjvBz3f
#>   Record: all
#>   Serialize with: yaml
#>   Match Requests on: method, uri
#>   Preserve Bytes?: FALSE
#>   Logging?: FALSE
#>   ignored hosts: 
#>   ignore localhost?: FALSE
#>   Write disk path: 
vcr_config_defaults()
#> $warn_on_empty_cassette
#> [1] TRUE
#> 
#> $verbose_errors
#> [1] FALSE
#> 
#> $write_disk_path
#> NULL
#> 
#> $filter_query_parameters
#> NULL
#> 
#> $filter_response_headers
#> NULL
#> 
#> $filter_request_headers
#> NULL
#> 
#> $filter_sensitive_data_regex
#> 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()
#> 
#> $clean_outdated_http_interactions
#> [1] FALSE
#> 
#> $re_record_interval
#> NULL
#> 
#> $turned_off
#> [1] FALSE
#> 
#> $preserve_exact_body_bytes
#> [1] FALSE
#> 
#> $ignore_request
#> NULL
#> 
#> $ignore_localhost
#> [1] FALSE
#> 
#> $ignore_hosts
#> NULL
#> 
#> $json_pretty
#> [1] FALSE
#> 
#> $serialize_with
#> [1] "yaml"
#> 
#> $allow_unused_http_interactions
#> [1] TRUE
#> 
#> $match_requests_on
#> [1] "method" "uri"   
#> 
#> $record
#> [1] "once"
#> 
#> $dir
#> NULL
#> 
vcr_configure(dir = tempdir(), ignore_hosts = "google.com")
vcr_configure(dir = tempdir(), ignore_localhost = TRUE)

# filter sensitive data
vcr_configure(dir = tempdir(),
  filter_sensitive_data = list(foo = "<bar>")
)
vcr_configure(dir = tempdir(),
  filter_sensitive_data = list(foo = "<bar>", hello = "<world>")
)