Skip to contents

Insert a cassette to record HTTP requests


  record = NULL,
  match_requests_on = NULL,
  update_content_length_header = FALSE,
  allow_playback_repeats = FALSE,
  serialize_with = NULL,
  persist_with = NULL,
  preserve_exact_body_bytes = NULL,
  re_record_interval = NULL,
  clean_outdated_http_interactions = NULL



The name of the cassette. vcr will check this to ensure it is a valid file name. Not allowed: spaces, file extensions, control characters (e.g., \n), illegal characters ('/', '?', '<', '>', '\', ':', '*', '|', and '\"'), dots alone (e.g., '.', '..'), Windows reserved words (e.g., 'com1'), trailing dots (can cause problems on Windows), names longer than 255 characters. See section "Cassette names"


The record mode (default: "once"). See recording for a complete list of the different recording modes.


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", "body" and "query"


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


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


(character) Which serializer to use. Valid values are "yaml" (default) and "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.


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


(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


(integer) How frequently (in seconds) the cassette should be re-recorded. default: NULL (not re-recorded)


(logical) Should outdated interactions be recorded back to file? default: FALSE


an object of class Cassette


Cassette names:

  • Should be meaningful so that it is obvious to you what test/function they relate to. Meaningful names are important so that you can quickly determine to what test file or test block a cassette belongs. Note that vcr cannot check that your cassette names are meaningful.

  • Should not be duplicated. Duplicated cassette names would lead to a test using the wrong cassette.

  • Should not have spaces. Spaces can lead to problems in using file paths.

  • Should not include a file extension. vcr handles file extensions for the user.

  • Should not have illegal characters that can lead to problems in using file paths: /, ?, <, >, \, :, *, |, and \"

  • Should not have control characters, e.g., \n

  • Should not have just dots, e.g., . or ..

  • Should not have Windows reserved words, e.g., com1

  • Should not have trailing dots

  • Should not be longer than 255 characters

vcr::check_cassette_names() is meant to be run during your tests, from a helper-*.R file inside the tests/testthat directory. It only checks that cassette names are not duplicated. Note that if you do need to have duplicated cassette names you can do so by using the allowed_duplicates parameter in check_cassette_names(). A helper function check_cassette_names() runs inside insert_cassette() that checks that cassettes do not have: spaces, file extensions, unaccepted characters (slashes).

Cassette options

Default values for arguments controlling cassette behavior are inherited from vcr's global configuration. See vcr_configure() for a complete list of options and their default settings. You can override these options for a specific cassette by changing an argument's value to something other than NULL when calling either insert_cassette() or use_cassette().


if (FALSE) {
vcr_configure(dir = tempdir())

(x <- insert_cassette(name = "leo5"))
cli <- crul::HttpClient$new(url = "")
x$new_recorded_interactions # 1 interaction
x$previously_recorded_interactions() # empty
webmockr::stub_registry() # not empty
# very important when using inject_cassette: eject when done
x$eject() # same as eject_cassette("leo5")
x$new_recorded_interactions # same, 1 interaction
x$previously_recorded_interactions() # now not empty
## stub_registry now empty, eject() calls webmockr::disable(), which
## calls the disable method for each of crul and httr adadapters,
## which calls webmockr's remove_stubs() method for each adapter

# cleanup
unlink(file.path(tempdir(), "leo5.yml"))