vcr updates (#112)

maelle · drmowinckels · sckott · web-flow · commit 575f529467da · 2025-10-23T17:11:52.000+02:00
* vcr updates * easier * fix * cli * fix * try * shall -> will = less formal, remove testthat:: as its already loaded (#113) * fix broken links * add link to intro about webmockr * Update _bookdown.yml * Apply suggestion from @sckott Co-authored-by: Scott Chamberlain <sckott@fastmail.com> * Update wholegames-vcr.Rmd Co-authored-by: Scott Chamberlain <sckott@fastmail.com> * Update wholegames-vcr.Rmd Co-authored-by: Scott Chamberlain <sckott@fastmail.com> * Update wholegames-vcr.Rmd Co-authored-by: Scott Chamberlain <sckott@fastmail.com> --------- Co-authored-by: Athanasia Monika Mowinckel <14014329+drmowinckels@users.noreply.github.com> Co-authored-by: Scott Chamberlain <sckott@fastmail.com>
diff --git a/.github/workflows/bookdown.yml b/.github/workflows/bookdown.yml
@@ -15,7 +15,7 @@ jobs:
       GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }}
       isExtPR: ${{ github.event.pull_request.head.repo.fork == true }}
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v5
 
       - uses: r-lib/actions/setup-pandoc@v2
       
@@ -28,7 +28,7 @@ jobs:
       - uses: r-lib/actions/setup-r-dependencies@v2
 
       - name: Cache bookdown results
-        uses: actions/cache@v2
+        uses: actions/cache@v4
         with:
           path: _bookdown_files
           key: bookdown-2-${{ hashFiles('**/*Rmd') }}
@@ -40,7 +40,7 @@ jobs:
           git config --global user.email "$GITHUB_ACTOR@users.noreply.github.com"
 
       - name: Build site
-        run: Rscript -e 'bookdown::render_book("index.Rmd", quiet = TRUE)'
+        run: Rscript -e 'options(knitr.duplicate.label = "allow");bookdown::render_book("index.Rmd", quiet = TRUE)'
         
       - name: Render book PDF
         run: Rscript -e 'bookdown::render_book("index.Rmd", "bookdown::pdf_book", output_dir = "pdfbook")'
diff --git a/07-vcr.Rmd b/07-vcr.Rmd
@@ -8,35 +8,14 @@ Record HTTP calls and replay them
 
 Check out <https://docs.ropensci.org/vcr/> for documentation on `vcr` functions.
 
-## Terminology {#terminology}
-
-```{r, echo=FALSE}
-get_vcr_doc("man/rmdhunks/glossary.Rmd")
-```
-
-```{r child='rmd-fragments/man/rmdhunks/glossary.Rmd', eval=TRUE} 
-```
 
 ## Design {#design}
 
-```{r, echo=FALSE}
-get_vcr_doc("man/rmdhunks/vcr-design.Rmd")
-```
-
-```{r child='rmd-fragments/man/rmdhunks/vcr-design.Rmd', eval=TRUE}
-```
+https://docs.ropensci.org/vcr/articles/design.html
 
 ## Basic usage {#vcr-basic-usage}
 
-```{r, echo=FALSE}
-get_vcr_doc("man/rmdhunks/basic-usage.Rmd")
-```
-
-```{r child='rmd-fragments/man/rmdhunks/basic-usage.Rmd', eval=TRUE} 
-```
-
-All components of both the request and response are preserved, so that the HTTP client (in this case `crul`) can reconstruct its own response just as it would if it wasn't using `vcr`.
-
+https://docs.ropensci.org/vcr/articles/vcr.html
 ## vcr enabled testing {#vcr-enabled-testing}
 
 ### check vs. test {#check-vs-test}
diff --git a/09-configuration.Rmd b/09-configuration.Rmd
@@ -8,9 +8,4 @@ knitr::opts_chunk$set(
 
 # Configure vcr {#vcr-configuration}
 
-```{r, echo=FALSE}
-get_vcr_doc("man/rmdhunks/configuration-vignette.Rmd")
-```
-
-```{r child='rmd-fragments/man/rmdhunks/configuration-vignette.Rmd', eval=TRUE} 
-```
+https://docs.ropensci.org/vcr/reference/vcr_configure.html
diff --git a/10-record-modes.Rmd b/10-record-modes.Rmd
@@ -9,9 +9,4 @@ knitr::opts_chunk$set(
 
 # Record modes {#record-modes}
 
-```{r, echo=FALSE}
-get_vcr_doc("man/rmdhunks/record-modes.Rmd")
-```
-
-```{r child='rmd-fragments/man/rmdhunks/record-modes.Rmd', eval=TRUE} 
-```
+https://docs.ropensci.org/vcr/articles/debugging.html
diff --git a/11-request-matching.Rmd b/11-request-matching.Rmd
@@ -9,9 +9,4 @@ knitr::opts_chunk$set(
 
 # Request matching {#request-matching}
 
-```{r, echo=FALSE}
-get_vcr_doc("man/rmdhunks/request-matching-vignette.Rmd")
-```
-
-```{r child='rmd-fragments/man/rmdhunks/request-matching-vignette.Rmd', eval=TRUE} 
-```
+https://docs.ropensci.org/vcr/articles/debugging.html
diff --git a/12-logging.Rmd b/12-logging.Rmd
@@ -9,9 +9,4 @@ knitr::opts_chunk$set(
 
 # Debugging your tests that use vcr 
 
-```{r, echo=FALSE}
-get_vcr_doc("man/rmdhunks/debugging-vignette.Rmd")
-```
-
-```{r child='rmd-fragments/man/rmdhunks/debugging-vignette.Rmd', eval=TRUE} 
-```
+https://docs.ropensci.org/vcr/articles/debugging.html
diff --git a/14-escape-hatches.Rmd b/14-escape-hatches.Rmd
@@ -8,9 +8,4 @@ knitr::opts_chunk$set(
 
 # Turning vcr on and off {#lightswitch}
 
-```{r, echo=FALSE}
-get_vcr_doc("man/rmdhunks/lightswitch.Rmd")
-```
-
-```{r child='rmd-fragments/man/rmdhunks/lightswitch.Rmd', eval=TRUE} 
-```
+https://docs.ropensci.org/vcr/reference/lightswitch.html
diff --git a/15-cassettes.Rmd b/15-cassettes.Rmd
@@ -9,12 +9,7 @@ knitr::opts_chunk$set(
 
 # Managing cassettes {#managing-cassettes}
 
-```{r, echo=FALSE}
-get_vcr_doc("man/rmdhunks/cassette-editing-vignette.Rmd")
-```
-
-```{r child='rmd-fragments/man/rmdhunks/cassette-editing-vignette.Rmd', eval=TRUE} 
-```
+https://docs.ropensci.org/vcr/articles/vcr.html?q=editing#cassette-files
 
 Be aware when you add your cassettes to either `.gitignore` and/or
 `.Rbuildignore`.
diff --git a/_bookdown.yml b/_bookdown.yml
@@ -16,4 +16,3 @@ rmd_files: ["index.Rmd",
            "10-record-modes.Rmd", "11-request-matching.Rmd", "12-logging.Rmd", "13-security.Rmd",
            "14-escape-hatches.Rmd", "15-cassettes.Rmd", "16-gotchas.Rmd",
            "18-session-info.Rmd", "404.Rmd"]
-before_chapter_script: "_common.R"
diff --git a/_common.R b/_common.R
diff --git a/intro-pkgs.Rmd b/intro-pkgs.Rmd
@@ -21,7 +21,7 @@ What are the challenges of HTTP testing?
 * 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.
 
-## webmockr
+## webmockr {#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:
 
diff --git a/wholegames-httptest.Rmd b/wholegames-httptest.Rmd
@@ -1,14 +1,16 @@
 # Use httptest {#httptest}
 
 In this chapter we aim at adding HTTP testing infrastructure to exemplighratia using httptest.
-For this, we start from the initial state of exemplighratia again. Back to square one!
+For this, we start from the initial state of exemplighratia again. 
+Back to square one!
 
 ::: {.alert .alert-dismissible .alert-warning} 
 Note that the `httptest::with_mock_dir()` function is only available in httptest version >= 4.0.0 (released on CRAN on 2021-02-01).
 :::
 
 ::: {.alert .alert-dismissible .alert-info} 
-[Corresponding pull request to exemplighratia](https://github.com/ropensci-books/exemplighratia/pull/9/files) Feel free to fork the repository to experiment yourself!
+[Corresponding pull request to exemplighratia](https://github.com/ropensci-books/exemplighratia/pull/9/files).
+Feel free to fork the repository to experiment yourself!
 :::
 
 ## Setup
@@ -27,7 +29,8 @@ library(httptest)
 When testthat runs tests, [files whose name starts with "setup" are always run first](https://testthat.r-lib.org/reference/test_dir.html#special-files).
 The setup file added by httptest loads httptest.
 
-We shall tweak it a bit to fool our package into believing there is an API token around in contexts where there is not. Since tests will use recorded responses when we are not recording, we do not need an actual API token when not recording, but we need `gh_organizations()` to not stop because `Sys.getenv("GITHUB_PAT")` returns nothing.
+We will tweak it a bit to fool our package into believing there is an API token around in contexts where there is not.
+Since tests will use recorded responses when we are not recording, we do not need an actual API token when not recording, but we need `gh_organizations()` to not stop because `Sys.getenv("GITHUB_PAT")` returns nothing.
 
 ```r
 library(httptest)
@@ -53,8 +56,8 @@ Let's tweak the test file for `gh_status_api`, it becomes
 ```r
 with_mock_dir("gh_api_status", {
   test_that("gh_api_status() works", {
-    testthat::expect_type(gh_api_status(), "character")
-    testthat::expect_equal(gh_api_status(), "operational")
+    expect_type(gh_api_status(), "character")
+    expect_equal(gh_api_status(), "operational")
   })
 })
 ```
@@ -82,13 +85,13 @@ The test file ` tests/testthat/test-organizations.R` is now:
 ```r
 with_mock_dir("gh_organizations", {
   test_that("gh_organizations works", {
-    testthat::expect_type(gh_organizations(), "character")
+    expect_type(gh_organizations(), "character")
   })
 })
 
 with_mock_dir("gh_organizations_error", {
   test_that("gh_organizations errors if the API doesn't behave", {
-    testthat::expect_error(gh_organizations())
+    expect_error(gh_organizations())
   })
 },
 simplify = FALSE)
@@ -101,9 +104,13 @@ In the second test there is more to unpack: how do we get a mock file correspond
 * We replaced `200L` with `502L` and removed the body, to end up with a very simple mock file under ` tests/testthat/gh_organizations_error/api.github.com/organizations-5377e8.R`
 
 ```r
-structure(list(url = "https://api.github.com/organizations?since=1",
-    status_code = 502L, headers = NULL), class = "response")
+structure(list(
+    url = "https://api.github.com/organizations?since=1",
+    status_code = 502L, 
+    headers = NULL), 
+  class = "response")
 ```
+
 * We re-run the tests. We got the expected error message.
 
 Without the HTTP testing infrastructure, testing for behavior of the package in case of API errors would be more difficult.
diff --git a/wholegames-httptest2.Rmd b/wholegames-httptest2.Rmd
@@ -72,7 +72,6 @@ We however dumbed it down by hand, to
 Let's tweak our other test, of `gh_organizations()`. 
 
 Here things get more exciting or complicated, as we also set out to adding a test of the error behavior.
-This inspired us to change error behavior a bit with a slightly more specific error message i.e. `httr2::resp_check_status(response)` became `httr2::resp_check_status(response, info = "Oops, try again later?")`. 
 
 The test file ` tests/testthat/test-organizations.R` is now:
 
diff --git a/wholegames-intro.Rmd b/wholegames-intro.Rmd
@@ -2,9 +2,9 @@
 
 # Introduction
 
-Similar to the [Whole Game chapter in the R packages book by Hadley Wickham and Jenny Bryan](https://r-pkgs.org/whole-game.html), we shall go through how to add HTTP tests to a minimal package.
-However, we will do it _three_ times to present alternative approaches: with [vcr](#vcr), [httptest](#httptest), [webfakes](#webfakes).
-After that exercise, we shall compare approaches: we will compare both packages that involve mocking i.e. [vcr vs. httptest](#mocking-pkgs-comparison); and all three HTTP packages in a [last chapter](#pkgs-comparison).
+Similar to the [Whole Game chapter in the R packages book by Hadley Wickham and Jenny Bryan](https://r-pkgs.org/whole-game.html), we will go through how to add HTTP tests to a minimal package.
+However, we will do it _four_ times to present alternative approaches: with [vcr](#vcr), [httptest](#httptest), [httptest2](#httptest2), [webfakes](#webfakes).
+After that exercise, we will compare approaches: we will compare both packages that involve mocking i.e. [vcr vs. httptest](#mocking-pkgs-comparison); and all three HTTP packages in a [last chapter](#pkgs-comparison).
 The next section will then present single topics such as "how to deal with authentication" in further details.
 
 ## Our example packages
@@ -19,12 +19,12 @@ Our example packages call web _APIs_ but the tools and concepts are applicable t
 :::
 
 GitHub V3 API works without authentication too, but at a lower rate.
-For the sake of having an example of a package _requiring_ authentication we shall assume the API is *not* usable without authentication.
+For the sake of having an example of a package _requiring_ authentication we will assume the API is *not* usable without authentication.
 Authentication is, here, the setting of a token in a HTTP header (so quite simple, compared to e.g. OAuth).
 
 GitHub Status API, on the contrary, does not necessitate authentication at all.
 
-So we shall create two functions, one that works without authentication, one that works with authentication.
+So we will create two functions, one that works without authentication, one that works with authentication.
 
 How did we create the packages?
 You are obviously free to use your own favorite workflow tools, but below we share our workflow using the [usethis package](https://r-pkgs.org/whole-game.html).
@@ -91,7 +91,8 @@ test_that("gh_api_status() works", {
 })
 ```
 
-* `use_r("organizations.R")` to add a second function. Note that an ideal version of this function would have some sort of callback in the retry, to call the `gh_api_status()` function (maybe with `httr2::req_retry()`'s `is_transient` argument).
+* `use_r("organizations.R")` (and `usethis::use_package("cli")`) to add a second function. 
+Note that an ideal version of this function would have some sort of callback in the retry, to call the `gh_api_status()` function (maybe with `httr2::req_retry()`'s `is_transient` argument).
 
 ```r
 gh_v3_url <- function() {
@@ -115,21 +116,19 @@ gh_v3_url <- function() {
 #' }
 gh_organizations <- function(since = 1) {
 
-  token <- Sys.getenv("GITHUB_PAT")
-
-  if (!nchar(token)) {
-    stop("No token provided! Set up the GITHUB_PAT environment variable please.")
+  if (!gh::gh_token_exists()) {
+    cli::cli_abort("No token provided! {.url https://usethis.r-lib.org/articles/git-credentials.html}.")
   }
 
+  token <- gh::gh_token()
+
   response <- httr2::request(gh_v3_url()) %>%
     httr2::req_url_path_append("organizations") %>%
     httr2::req_url_query(since = since) %>%
     httr2::req_headers("Authorization" = paste("token", token)) %>%
     httr2::req_retry(max_tries = 3, max_seconds = 120) %>%
     httr2::req_perform()
 
-  httr2::resp_check_status(response)
-
   content <- httr2::resp_body_json(response)
 
   purrr::map_chr(content, "login")
@@ -143,7 +142,7 @@ gh_organizations <- function(since = 1) {
 
 ```r
 test_that("gh_organizations works", {
-  testthat::expect_type(gh_organizations(), "character")
+  expect_type(gh_organizations(), "character")
 })
 
 ```
diff --git a/wholegames-vcr.Rmd b/wholegames-vcr.Rmd
