Skip to contents

How vcr works, in a lot of details

Source: vignettes/internals.Rmd
internals.Rmd

The steps

  1. Use either vcr::use_cassette() or vcr::insert_cassette()
  1. If you use vcr::insert_cassette(), make sure to run vcr::eject_cassette() when you’re done to stop recording
  1. When you first run a request with vcr there’s no cached data to use, so we allow HTTP requests until your request is done.
  2. Before we run the real HTTP request, we “stub” the request with webmockr so that future requests will match the stub. This stub is an R6 class with details of the interaction (request + response), but is not on disk.
  3. After the stub is made, we run the real HTTP request.
  4. We then disallow HTTP requests so that if the request is done again we use the cached response
  5. The last thing we do is write the HTTP interaction to disk in a mostly human readable form.

When you run that request again using vcr::use_cassette() or vcr::insert_cassette():

  • We use webmockr to match the request to cached requests, and since we stubbed the request the first time we used the cached response.

Of course if you do a different request, even slightly (but depending on which matching format you decided to use), then the request will have no matching stub and no cached response, and then a real HTTP request is done - we then cache it, then subsequent requests will pull from that cached response.

webmockr has adapters for each R client (crul, httr and httr2) - so that we actually intercept HTTP requests when webmockr is loaded and the user turns it on. So, webmockr doesn’t actually require an internet or localhost connection at all, but can do its thing just fine by matching on whatever the user requests to match on. In fact, webmockr doesn’t allow real HTTP requests by default, but can be toggled off of course.

The main use case we are going for in vcr is to deal with real HTTP requests and responses, so we allow real HTTP requests when we need to, and turn it off when we don’t.

This gives us a very flexible and powerful framework where we can support webmockr and vcr integration for any number of R clients for HTTP requests and support many different formats serialized to disk.