Skip to main content

HTTP testing in R

4 Packages for HTTP testing

A brief presentation of packages you’ll “meet” again later in this book!

4.1 Why do we need special packages for HTTP testing?

Packages for HTTP testing are useful because there are challenges to HTTP testing. Packages for HTTP testing help you solve these challenges, rather than letting you solve them with some homegrown solutions (you can still choose to do that, of course).

What are the challenges of HTTP testing?

  • Having tests depend on an internet connection is not ideal.
  • Having tests depend on having secrets for authentication at hand is not ideal.
  • Having tests for situations that are hard to trigger (e.g. the failure of a remote server) is tricky.

4.2 webmockr

webmockr, maintained by Scott Chamberlain, is an R package to help you “mock” HTTP requests. What does “mock” mean? Mock refers to the fact that we’re faking the response. Here is how it works:

  • You “stub” a request. That is, you set rules for what HTTP request you’d like to respond to with a fake response. E.g. a rule might be a method, or a URL.
  • You also can set rules for what fake response you’d like to respond with, if anything (if nothing, then we give you NULL).
  • Then you make HTTP requests, and those that match your stub i.e. set of rules will return what you requested be returned.
  • While webmockr is in use, real HTTP interactions are not allowed. Therefore you need to stub all possible HTTP requests happening via your code. You’ll get error messages for HTTP requests not covered by any stub.
  • There is no recording interactions to disk at all, just mocked responses given as the user specifies in the R session.

webmockr works with crul, httr, and httr2.

webmockr is quite low-level and not the first tool you’ll use directly in your day-to-day HTTP testing. You may never use it directly but if you use vcr it’s one of its foundations.

webmockr was inspired by the Ruby webmock gem.

4.3 What is vcr?

The short version is vcr, maintained by Scott Chamberlain, helps you stub HTTP requests so you don’t have to repeat HTTP requests, mostly in your unit tests. It uses the power of webmockr, with a higher level interface.

When using vcr in tests, the first time you run a test, the API response is stored in a YAML or JSON file. All subsequent runs of the test use that local file instead of really calling the API. Therefore tests work independently of an internet connection.

vcr was inspired by the Ruby vcr gem.

vcr works for packages using httr, httr2 or crul.

Direct link to {vcr} (& {webmockr}) demo

4.4 What is httptest?

httptest, maintained by Neal Richardson, uses mocked API responses (like vcr). It “enables one to test all of the logic on the R sides of the API in your package without requiring access to the remote service.”

Contrary to vcr, httptest also lets you define mock files by hand (copying from API docs, or dumbing down real responses), whereas with vcr all mock files come from recording real interactions (although you can choose to edit {vcr} mock files after recording).

httptest works for packages using httr.

Direct link to {httptest} demo

The differences and similarities between httptest and vcr will become clearer in the chapters where we provide the whole games for each of them.

4.5 What is httptest2?

httptest2, maintained by Neal Richardson, is like httptest, but for httr2.

Direct link to {httptest2} demo

With vcr, httptest and httptest2 the tests will use some sort of fake API responses.

In vcr they are called fixtures or cassettes. In httptest and httptest2 they are called mock files.

4.6 What is webfakes?

webfakes, maintained by Gábor Csárdi, provides an alternative (complementary?) tool for HTTP testing. It will let you fake a whole web service, potentially outputting responses from mock files you’ll have created. It does not help with recording fake responses. Because it runs a fake web service, you can even interact with said web service in your browser or with curl in the command line.

webfakes works with packages using any HTTP package (i.e. it works with curl, crul, httr, or httr2).

Direct link to {webfakes} demo

4.7 testthat

testthat, maintained by Hadley Wickham, is not a package specifically for HTTP testing; it is a package for general-purpose unit testing of R packages. In this book we will assume that is what you use, because of its popularity.

If you use an alternative like tinytest,

4.8 Conclusion

Now that you have an idea of the tools we can use for HTTP testing, we’ll now create a minimal package and then amend it in three versions tested with

Our minimal package will use httr (except for httptest2, where we’ll use httr2). However, it will help you understand concepts even if you end up using crul or curl.1