vcr (version 0.2.6)

use_cassette: Use a cassette

Description

Use a cassette

Usage

use_cassette(name, ..., record = "once",
  match_requests_on = c("method", "uri"),
  update_content_length_header = FALSE, allow_playback_repeats = FALSE,
  serialize_with = "yaml", persist_with = "FileSystem",
  preserve_exact_body_bytes = FALSE)

Arguments

name

The name of the cassette. vcr will sanitize this to ensure it is a valid file name.

...

a block of code to evalulate, wrapped in curly braces. required. if you don't pass a code block you'll get a stop message. if you can't pass a code block use instead insert_cassette()

record

The record mode. Default: "once". In the future we'll support "once", "all", "none", "new_episodes". See recording for more information

match_requests_on

List of request matchers to use to determine what recorded HTTP interaction to replay. Defaults to ["method", "uri"]. The built-in matchers are "method", "uri", "host", "path", "headers" and "body"

update_content_length_header

(logical) Whether or not to overwrite the Content-Length header of the responses to match the length of the response body. Default: FALSE

allow_playback_repeats

(logical) Whether or not to allow a single HTTP interaction to be played back multiple times. Default: FALSE.

serialize_with

(character) Which serializer to use. Valid values are "yaml" (default), the only one supported for now.

persist_with

(character) Which cassette persister to use. Default: "file_system". You can also register and use a custom persister.

preserve_exact_body_bytes

(logical) Whether or not to base64 encode the bytes of the requests and responses for this cassette when serializing it. See also preserve_exact_body_bytes in vcr_configure(). Default: FALSE

Value

an object of class Cassette

Behavior

This function handles a few different scenarios:

• when everything runs smoothly, and we return a Cassette class object so you can inspect the cassette, and the cassette is ejected

• when there is an invalid parameter input on cassette creation, we fail with a useful message, we don't return a cassette, and the cassette is ejected

• when there is an error in calling your passed in code block, we return with a useful message, and since we use on.exit() the cassette is still ejected even though there was an error, but you don't get an object back

Cassettes on disk

Note that "eject" only means that the R session cassette is no longer in use. If any interactions were recorded to disk, then there is a file on disk with those interactions.

Using with tests (specifically <span class="pkg">testthat</span>)

There's a few ways to get correct line numbers for failed tests and one way to not get correct line numbers:

Correct: Either wrap your test_that() block inside your use_cassette() block, OR if you put your use_cassette() block inside your test_that() block put your testthat expectations outside of the use_cassette() block.

Incorrect: By wrapping the use_cassette() block inside your test_that() block with your testthat expectations inside the use_cassette() block, you'll only get the line number that the use_cassette() block starts on.

Details

A run down of the family of top level vcr functions

• use_cassette Initializes a cassette. Returns the inserted cassette.

• insert_cassette Internally used within use_cassette

• eject_cassette ejects the current cassette. The cassette will no longer be used. In addition, any newly recorded HTTP interactions will be written to disk.

See Also

insert_cassette(), eject_cassette()

Examples

# NOT RUN {
library(vcr)
library(crul)
vcr_configure(dir = tempdir())

use_cassette(name = "apple7", {
  cli <- HttpClient$new(url = "https://httpbin.org")
  resp <- cli$get("get")
})
readLines(file.path(tempdir(), "apple7.yml"))

# preserve exact body bytes - records in base64 encoding
use_cassette("things4", {
  cli <- crul::HttpClient$new(url = "https://httpbin.org")
  bbb <- cli$get("get")
}, preserve_exact_body_bytes = TRUE)
## see the body string value in the output here
readLines(file.path(tempdir(), "things4.yml"))

# cleanup
unlink(file.path(tempdir(), c("things4.yml", "apple7.yml")))


# with httr
library(vcr)
library(httr)
vcr_configure(dir = tempdir(), log = TRUE)

use_cassette(name = "stuff350", {
  res <- GET("https://httpbin.org/get")
})
readLines(file.path(tempdir(), "stuff350.yml"))

use_cassette(name = "catfact456", {
  res <- GET("https://catfact.ninja/fact")
})

# record mode: none
library(crul)
vcr_configure(dir = tempdir())

## make a connection first
conn <- crul::HttpClient$new("https://eu.httpbin.org")
## this errors because 'none' disallows any new requests
# use_cassette("none_eg", (res2 <- conn$get("get")), record = "none")
## first use record mode 'once' to record to a cassette
one <- use_cassette("none_eg", (res <- conn$get("get")), record = "once")
one; res
## then use record mode 'none' to see it's behavior
two <- use_cassette("none_eg", (res2 <- conn$get("get")), record = "none")
two; res2
# }