---
title: "vcr configuration"
author: "Scott Chamberlain"
date: "`r Sys.Date()`"
output:
  html_document:
    toc: true
    toc_float: true
    theme: readable
vignette: >
  %\VignetteIndexEntry{2. vcr configuration}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

vcr configuration
=================

`vcr` configuration

```{r}
library("vcr")
```

## Get configuration

Use `vcr_configuration()` to get the current configuration.

```{r}
vcr_configuration()
```

You can also get the default configuration variables via `vcr_config_defaults()`

```{r}
vcr_config_defaults()
```

These defaults are set when you load `vcr` - you can override any of them as described below.

## Set configuration variables

Use `vcr_configure()` to set configuration variables.

For example, set a single variable:

```{r}
vcr_configure(
  dir = "foobar/vcr_cassettes"
)
```

Or many at once:

```{r}
vcr_configure(
  dir = "foobar/vcr_cassettes",
  record = "all"
)
```

## Re-set to defaults

```{r}
vcr_configure_reset()
```

## Details on some of the config options

### dir

Directory where cassettes are stored

```{r}
vcr_configure(dir = "new/path")
```

### record

The record mode

One of: 'all', 'none', 'new_episodes', 'once'. See `?recording` for info on the options

```{r}
vcr_configure(record = "new_episodes")
```

### match_requests_on 

Customize how `vcr` matches requests

```{r}
vcr_configure(match_requests_on = c('query', 'headers'))
```

### allow_unused_http_interactions 

Allow HTTP connections when no cassette

Default is `TRUE`, and thus does not error when http interactions are unused. You 
can set to `FALSE` in which case vcr errors when a cassette is ejected and 
not all http interactions have been used.

```{r}
vcr_configure(allow_unused_http_interactions = FALSE)
```

### serialize_with

Which serializer to use. Right now only option is "yaml"

```{r}
vcr_configure(serialize_with = "yaml")
```

### persist_with

Which persister to use. Right now only option is "FileSystem"

```{r}
vcr_configure(persist_with = "FileSystem")
```

### ignoring some requests

**ignore_hosts**

Specify particular hosts to ignore. By ignore, we mean that 
real HTTP requests to the ignored host will be allowed to occur, while
all others will not.

```{r}
vcr_configure(ignore_hosts = "google.com")
```

**ignore_localhost**

Ignore all localhost requests

```{r}
vcr_configure(ignore_localhost = TRUE)
```

**ignore_request**

THIS DOESN'T WORK YET

**How to ignore requests**

For ignoring requests, you can for example, have real http requests go through (ignored by `vcr`) while other requests are handled by `vcr`. For example, let's say you want requests to `google.com` to be ignored:

```{r eval=FALSE}
vcr_configure(ignore_hosts = "google.com")
use_cassette("foo_bar", {
  crul::HttpClient$new("https://httpbin.org/get")$get()
  crul::HttpClient$new("https://google.com")$get()
})
```

The request to httpbin.org will be handled by `vcr`, a cassette created for the request/response to that url, while the google.com request will be ignored and not cached at all.

Note: ignoring requests only works for the `crul` package for now; it should work for `httr` in a later `vcr` version.

### uri_parse

Which uri parser to use

By default we use `crul::url_parse`, but you can use a different one. Remember 
to pass in the function quoted, and namespaced.

```{r}
vcr_configure(uri_parser = "urltools::url_parse")
```

### preserve_exact_body_bytes

Some HTTP servers are not well-behaved and respond with invalid data. Set 
`preserve_exact_body_bytes` to `TRUE` to base64 encode the result body in 
order to preserve the bytes exactly as-is. `vcr` does not do this by
default, since base64-encoding the string removes the human readability 
of the cassette.

```{r}
vcr_configure(preserve_exact_body_bytes = TRUE)
```

### filter_sensitive_data 

A named list of values to replace. Sometimes your package or script is 
working with sensitive tokens/keys, which you do not want to accidentally 
share with the world.

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.

```{r}
vcr_configure(
  filter_sensitive_data = list("<some_api_key>" = Sys.getenv('MY_API_KEY'))
)
```

Before recording to disk, the env var `MY_API_KEY` is retrieved from your machine, 
and we find instances of it, and replace with `<some_api_key>`. When replaying 
to create the HTTP response object we put the real value of the env var 
back in place. 

## More documentation

Check out the [http testing book](https://books.ropensci.org/http-testing/) for a lot more documentation on `vcr`, `webmockr`, and `crul`
