secrets setup

vignettes/vcr.Rmd

@@ -77,7 +77,7 @@ This will:
 
 ### Protecting secrets
 
-Secrets often turn up in API work. A common example is an api-key. VCR _records_ the full response from the API, which will include things like api-keys if they are present. You need to be able to protect these pieces of information from things like version control, but still have them be accessible to the tests so that they can run as expected. The `vcr_configure` function has the `filter_sensitive_data` argument function for just this situation. The `filter_sensitive_data` argument takes a named list where the _name_ of the list is the string that will be used in the recorded cassettes _instead of_ the secret, which is the list _item_. `vcr` will manage the replacement of that for you, so all you need to do is to edit your `setup-vcr.R` file like this:
+Secrets often turn up in API work. A common example is an API key. VCR _records_ the full response from the API, which will include things like API keys if they are present. You need to be able to protect these pieces of information from things like version control, but still have them be accessible to the tests so that they can run as expected. The `vcr_configure` function has the `filter_sensitive_data` argument function for just this situation. The `filter_sensitive_data` argument takes a named list where the _name_ of the list is the string that will be used in the recorded cassettes _instead of_ the secret, which is the list _item_. `vcr` will manage the replacement of that for you, so all you need to do is to edit your `setup-vcr.R` file like this:
 
 ```r
 library("vcr")
@@ -88,6 +88,8 @@ invisible(vcr::vcr_configure(
 vcr::check_cassette_names()
 ```
 
+Notice we wrote `Sys.getenv('APIKEY')` and not the API key directly, otherwise you'd have written your API key to a file that might end up in a public repo.
+
 It is normal to keep your secrets as environmental variables local to your system. The addition of the line above will instruct `vcr` to replace any string in cassettes it records that are equivalent to your string which is stored as the `APIKEY` environmental variable with the masking string `<<<my_api_key>>>`. In practice, you might get a `YAML` that looks a little like this:
 
 ```yaml
@@ -103,7 +105,21 @@ http_interactions:
 ```
 Here, my `APIKEY` environmental variable would have been stored as the `api-key` value, but `vcr` has realised this and recorded the string `<<<my_api_key>>>` instead.
 
-When `vcr` then checks a test against this _local_ version of the response, it will then compare the `APIKEY` it _receives_ in the test against the one it _sources_ from the one sourced in the `vcr_configure`, which in this case comes from the local environment. Therefore, if you have to change the `APIKEY` in the future, the test will _still_ work as long as the local `APIKEY` environmental is up to date.
+Once the cassette is recorded, `vcr` no longer needs the API key as no real requests will be made.
+Furthermore, as by default requests matching does not include the API key, things will work.
+
+**Now, how to ensure tests work in the absence of a real API key?**
+
+E.g. to have tests pass on continuous integration for external pull requests to your code repository.
+
+* vcr does not need an actual API key for requests once the cassettes are created, as no real requests will be made.
+* you still need to fool your _package_ into believing there is an API key as it will construct requests with it. So add the following lines to a testthat setup file (e.g. `tests/testthat/setup-vcr.R`)
+
+```r
+if (!nzchar(Sys.getenv("APIKEY"))) {
+  Sys.setenv("APIKEY" = "foobar")
+}
+```
 
 #### Using an `.Renviron`