Package 'vcr'

Description

List cassettes, get current cassette, etc.

Usage

cassettes()

current_cassette()

current_cassette_recording()

current_cassette_replaying()

cassette_path()

Details

• cassettes(): returns all active cassettes in the current session.

• current_cassette(): returns NULL when no cassettes are in use; returns the current cassette (a Cassette object) when one is in use

• currrent_cassette_recording() and current_cassette_replaying(): tell you if the current cassette is recording and/or replaying. They both return FALSE if there is no cassette in use.

• cassette_path(): returns the current directory path where cassettes will be stored

Examples

vcr_configure(dir = tempdir())

# list all cassettes
cassettes()

# list the currently active cassette
insert_cassette("stuffthings")
current_cassette()
cassettes()

eject_cassette()
cassettes()


# list the path to cassettes
cassette_path()
vcr_configure(dir = file.path(tempdir(), "foo"))
cassette_path()

vcr_configure_reset()

Description

insert_example_cassette() is a wrapper around insert_cassette() that stores cassettes in ⁠inst/_vcr/⁠. Call it in the first line of your examples (typically wrapped in ⁠\dontshow{}⁠), and call eject_cassette() on the last line.

Run the example manually once to record the vignettte, then it will be replayed during ⁠R CMD check⁠, ensuring that your example no longer uses the internet.

Usage

insert_example_cassette(
  name,
  package,
  record = NULL,
  match_requests_on = NULL,
  serialize_with = NULL,
  preserve_exact_body_bytes = NULL,
  re_record_interval = NULL
)

Arguments

Examples

# In this example I'm showing the insert and eject commands, but you'd
# usually wrap these in \dontshow{} so the user doesn't see them and
# think that they're something they need to copy.

insert_example_cassette("httpbin-get", package = "vcr")

req <- httr2::request("https://hb.cran.dev/get")
resp <- httr2::req_perform(req)

str(httr2::resp_body_json(resp))

eject_cassette()

Description

local_cassette() and use_cassette() set the VCR_IS_RECORDING and VCR_IS_REPLAYING environment variables to make it easy to determine vcr state without taking a dependency on vcr. These functions show you how to use them; we expect you to copy and paste these functions into your own package

Usage

is_recording()

is_replaying()

Value

TRUE or FALSE.

Description

• turn_on() and turn_off() turn on and off for the whole session.

• turned_off(code) temporarily turns off while code is running, guaranteeing that you make a real HTTP request.

• turned_on() reports on if vcr is turned on or not.

• skip_if_vcr_off() skips a test if vcr is turned off. This is occasionally useful if you're using a cassette to simulate a faked request, or if the real request would return different values (e.g. you're testing date parsing and the request returns the current date).

You can also control the default behaviour in a new session by setting the following environment variables before R starts:

• Use VCR_TURN_OFF=true to suppress all vcr usage, ignoring all cassettes. This is useful for CI/CD workflows where you want to ensure the test suite is run against the live API.

• Set VCR_TURNED_OFF=true to turn off vcr, but still use cassettes.

Usage

turn_on()

turn_off(ignore_cassettes = FALSE)

turned_off(code, ignore_cassettes = FALSE)

turned_on()

skip_if_vcr_off()

Arguments

Examples

# By default, vcr is turned on
turned_on()

# you can turn off for the rest of the session
turn_off()
turned_on()
# turn on again
turn_on()

# or just turn it on turn off temporarily
turned_off({
  # some HTTP requests here
  turned_on()
})

Description

setup_knitr() registers a knitr hook to make it easy to use vcr inside a vignette. First call setup_knitr() in your setup chunk (or other chunk early in the document):

```{r setup}
#| include: false
vcr::setup_knitr()
```

Then, in a chunk where you want to use a cassette, set the cassette chunk option to the name of the cassette:

```{r}
#| cassette: name
req <- httr2::request("http://r-project.org")
resp <- httr2::req_perform(req)
```

Or if you have labelled the chunk, you can use cassette: true to use the chunk label as the cassette name:

```{r}
#| label: cassette-name
#| cassette: true
req <- httr2::request("http://r-project.org")
resp <- httr2::req_perform(req)
```

You can build your vignettes however you usually do (from the command line, with pkgdown, with RStudio/Positron, etc).

Usage

setup_knitr(prefix = NULL, dir = "_vcr", ...)

Arguments

Description

use_cassette(...) uses a cassette for the code in ...; local_cassette() uses a cassette for the current function scope (e.g. for one test). Learn more in vignette("vcr").

Note that defaults for most arguments are controlled by vcr_configure(), so you may want to use that instead if you are changing the defaults for all cassettes.

Usage

use_cassette(
  name,
  ...,
  dir = NULL,
  record = NULL,
  match_requests_on = NULL,
  serialize_with = NULL,
  preserve_exact_body_bytes = NULL,
  re_record_interval = NULL,
  warn_on_empty = NULL
)

local_cassette(
  name,
  dir = NULL,
  record = NULL,
  match_requests_on = NULL,
  serialize_with = NULL,
  preserve_exact_body_bytes = NULL,
  re_record_interval = NULL,
  warn_on_empty = NULL,
  frame = parent.frame()
)

Arguments

See Also

insert_cassette() and eject_cassette() for the underlying functions.

Description

Configurable options that define vcr's default behavior.

Usage

vcr_configure(
  dir,
  record,
  match_requests_on,
  serialize_with,
  json_pretty,
  ignore_hosts,
  ignore_localhost,
  preserve_exact_body_bytes,
  turned_off,
  re_record_interval,
  log,
  log_opts,
  filter_sensitive_data,
  filter_sensitive_data_regex,
  filter_request_headers,
  filter_response_headers,
  filter_query_parameters,
  write_disk_path,
  warn_on_empty_cassette
)

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

vcr_configure_reset()

vcr_configuration()

vcr_config_defaults()

Arguments

Examples

vcr_configure(dir = tempdir())
vcr_configure(dir = tempdir(), record = "all")
vcr_configuration()
vcr_config_defaults()
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>")
)

Description

By default, logging is disabled, but you can easily enable for the entire session with vcr_configure_log() or for just one test with local_vcr_configure_log().

Usage

vcr_configure_log(
  log = TRUE,
  file = stderr(),
  include_date = NULL,
  log_prefix = "Cassette"
)

local_vcr_configure_log(
  log = TRUE,
  file = stderr(),
  include_date = NULL,
  log_prefix = "Cassette",
  frame = parent.frame()
)

Arguments

Examples

# The default logs to stderr()
vcr_configure_log()

# But you might want to log to a file
vcr_configure_log(file = file.path(tempdir(), "vcr.log"))

Description

When debugging, it's often useful to see the last request and response respectively. These functions give you what would have been recorded to disk or replayed from disk. If the last request wasn't recorded, and there was no matching request, vcr_last_response will return NULL.

Usage

vcr_last_request()

vcr_last_response()

Description

This function, similar to testthat::test_path(), is designed to work both interactively and during tests, locating files in the ⁠tests/⁠ directory.

Usage

vcr_test_path(...)

Arguments

Value

A character vector giving the path

Note

vcr_test_path() assumes you are using testthat for your unit tests.

Examples

if (interactive()) {
vcr_test_path("fixtures")
}