January 26, 2021 From rOpenSci (https://deploy-preview-488--ropensci.netlify.app/blog/2021/01/26/http-testing-book/). Except where otherwise noted, content on this site is licensed under the CC-BY license.
More and more R packages access resources on the web, and play crucial roles in workflows. Examples from the rOpenSci suite of packages include rromeo, GSODR, qualtRics, rnassqs, and many, many others. Like for all other packages, appropriate unit testing can make them more robust. However, unit testing of these packages can bring special challenges: dependence of tests on a good internet connection, testing in the absence of authentication secrets, etc. Having tests fail due to resources being down or slow, during development or on CRAN, means a time loss for everyone involved (slower development, messages from CRAN). Although many packages accessing remote resources are well tested, there used to be a lack of resources around best practices… But now there is one great information source, our HTTP testing in R online book! 🎉
The best guidance about HTTP testing for R packages used to be an rOpenSci forum entry by Noam Ross that pre-dated the development of relatively new packages for HTTP testing that have now been released on CRAN: vcr and webmockr by Scott Chamberlain, httptest by Neal Richardson, webfakes by Gábor Csárdi.
These packages help make HTTP testing smooth to set up and resilient to internet connection failures, which means faster tests, tests running well even when on a spotty internet connection, and less burden on the remote resources.
We have updated the HTTP testing in R online book to make it a free, central reference for developers of R packages accessing web resources, to help them have a faster and more robust development. Scott created the book a while back, as central documentation for his packages crul, vcr and webmockr. Maëlle got funding from the R Consortium to expand the scope of the book. Thank you, R Consortium! Thanks also to Scott, Adam Sparks, Matthias Grenié and Neal Richardson for contributing to the project proposal. Thanks also to Gábor Csárdi who was also consulted… even before he created webfakes! Last but not least, thanks to recent readers of the book like Dave Parr, Lluís Revilla Sancho and Hugo Gruson for useful feedback.
The book still has advanced content about webmockr and vcr, but now this comes after new content.
An introduction (how original), giving some basic information and resource suggestions around HTTP in R and graceful HTTP R packages as well as the reason why we need special packages for HTTP testing.
A Whole Games section inspired by the Whole Game chapter of the R packages book by Hadley Wickham and Jenny Bryan. We created a minimal R package interacting with two web APIs and added tests to it (of normal behavior, of behavior when there is an API error) three times
The section also features a comparison of the two packages using mock files / cassettes for storing API responses or interactions (vcr and httptest), and a comparison of all packages.
An Advanced Topics section about topics transverse to all packages.
A conclusion (again, how original) underlining what the next steps are. In particular, we encourage you to read the docs of the HTTP package(s) you end up using. For webmockr and vcr, these docs also live in the same book so you don’t have far to go.
Whilst writing chapters Maëlle filed several docs and feature requests to vcr, httptest, webfakes. All three maintainers were very kind and receptive.
httptest::with_mock_dir() function was contributed as a result of Maëlle’s work.Besides, the book itself is an early adopter of a brand-new bookdown template by Hadley Wickham, bookdown::bs4_book(), which you might want to check out for your own bookish endeavors!
It’s only available in the development version of bookdown at the moment of writing, and there quite a few features still in the work.
As for deployment, we’d recommend looking at the GitHub Actions workflow for the R packages book that we drew inspiration from.
While we are happy with our “HTTP testing in R” book, we are committed to updating and improving it! Have a look at the book issue tracker, and feel free to give us feedback there or on rOpenSci forum. Comments by experts and newbies and any expertise level in-between are most welcome! Happy HTTP testing!
