15-cassettes.Rmd

```{r echo = FALSE}
knitr::opts_chunk$set(
  comment = "#>",
  warning = FALSE,
  message = FALSE
)
```


# Managing cassettes {#managing-cassettes}

```{r, echo=FALSE}
get_vcr_doc("man/rmdhunks/cassette-editing-vignette.Rmd")
```

```{r child='rmd-fragments/man/rmdhunks/cassette-editing-vignette.Rmd', eval=TRUE} 
```

Be aware when you add your cassettes to either `.gitignore` and/or
`.Rbuildignore`.

## gitignore cassettes {#gitignore-cassettes}

The [.gitignore][gitignorefile] file lets you tell [git][] what files to
ignore - those files are not tracked by git and if you share the git
repository to the public web, those files in the `.gitignore` file
won't be shared in the public version.

When using `vcr` you may want to include your cassettes in the
`.gitignore` file. You may wan to when your cassettes contain sensitive
data that you don't want to have on the internet & dont want to hide
with [filter_sensitive_data](#api-keys-security).

You may want to have your cassettes included in your GitHub repo, both
to be present when tests run on CI, and when others run your tests.

There's no correct answer on whether to gitignore your cassettes.
Think about security implications and whether you want CI and human
contributors to use previously created cassettes or to create/use their
own.

## Rbuildignore cassettes {#rbuildignore-cassettes}

The [.Rbuildignore][Rbuildignore] file is used to tell R to ignore
certain files/directories.

There's not a clear use case for why you'd want to add vcr cassettes
to your `.Rbuildignore` file, but if you do be aware that will affect
your vcr enabled tests.

## sharing cassettes {#sharing-cassettes}

Sometimes you may want to share or re-use cassettes across tests, 
for example to [reduce the size for package sources](#cran-preparedness) or 
to test different functionality of your package functions 
that make the same query under the hood. 

To do so, you can use the same cassette name for multiple `vcr::use_cassette()`
calls.
`vcr::check_cassette_names()` will complain about duplicate cassette 
names, preventing you from accidentally re-using cassettes, however.
To allow duplicates, you can provide a character vector of the cassette names 
you want to re-use to the `allowed_duplicates` argument of 
`vcr::check_cassette_names()`. 
That way you can use the same cassette across multiple tests.

## deleting cassettes

Removing a cassette is as easy as deleting in your file finder,
or from the command line, or from within a text editor or RStudio.

If you delete a cassette, on the next test run the cassette will
be recorded again.

If you do want to re-record a test to a cassette, instead of
deleting the file you can toggle [record modes](#record-modes).

## cassette file types

For right now the only persistence option is yaml. So all files
have a `.yml` extension.

When other persister options are added, additional file types
may be found. The next persister type is likely to be JSON,
so if you use that option, you'd have `.json` files instead of
`.yml` files.


[gitignorefile]: https://guide.freecodecamp.org/git/gitignore/
[Rbuildignore]: https://cran.r-project.org/doc/manuals/r-release/R-exts.html#index-_002eRbuildignore-file