✨ More proofreading ✨

Author: hadley

vignettes/challenging-tests.Rmd

@@ -20,7 +20,7 @@ snapper$start_file("snapshotting.Rmd", "test")
 Sys.setenv(TESTTHAT_PKG = "testthat")
 ```
 
-This vignette is a quick reference guide for testing challenging functions. It's organised by the problem, rather than the technique used to solve it, so you can quickly skim the whole vignette, spot the problem you're facing, then learn more about useful tools for solving it.
+This vignette is a quick reference guide for testing challenging functions. It's organized by the problem, rather than the technique used to solve it, so you can quickly skim the whole vignette, spot the problem you're facing, then learn more about useful tools for solving it.
 
 ## Options and environment variables
 
@@ -63,7 +63,7 @@ test_that("three dice adds values of individual calls", {
 
 ## Some tests can't be run in some circumstances
 
-You can skip a test without passing or failing if it's not possible to run it in the current environment (e.g. it's OS dependent, or it only works interactively, or it shouldn't be tested on CRAN). Learn more in `vignette("skipping")`.
+You can skip a test without passing or failing if it's not possible to run it in the current environment (e.g., it's OS dependent, or it only works interactively, or it shouldn't be tested on CRAN). Learn more in `vignette("skipping")`.
 
 ## HTTP requests
 
@@ -145,4 +145,4 @@ Learn more in `vignette("mocking")`.
 
 ## User-facing text
 
-Errors, warnings, and other user-facing text should be tested to ensure they're consistent and actionable. Obviously you can't test this 100% automatically, but you can ensure that such messaging is clearly shown in PRs so another human can take a look. This is the point of snapshot tests; learn more in `vignette("snapshotting")`.
+Errors, warnings, and other user-facing text should be tested to ensure they're consistent and actionable. Obviously, you can't test this 100% automatically, but you can ensure that such messaging is clearly shown in PRs so another human can take a look. This is the point of snapshot tests; learn more in `vignette("snapshotting")`.

vignettes/custom-expectation.Rmd

@@ -43,7 +43,7 @@ expect_length <- function(object, n) {
 }
 ```
 
-The first step in any expectation is to use `quasi_label()` to capture a "labelled value", i.e. a list that contains both the value (`$val`) for testing and a label (`$lab`) for messaging. This is a pattern that exists for fairly esoteric reasons; you don't need to understand it, just copy and paste it 🙂.
+The first step in any expectation is to use `quasi_label()` to capture a "labelled value", i.e., a list that contains both the value (`$val`) for testing and a label (`$lab`) for messaging. This is a pattern that exists for fairly esoteric reasons; you don't need to understand it, just copy and paste it 🙂.
 
 Next you need to check each way that `object` could violate the expectation. In this case, there's only one check, but in more complicated cases there can be multiple checks. In most cases, it's easier to check for violations one by one, using early returns to `fail()`. This makes it easier to write informative failure messages that first describe what was expected and then what was actually seen.
 
@@ -87,7 +87,7 @@ The following sections show you a few more variations, loosely based on existing
 
 ### `expect_vector_length()`
 
-Let's make `expect_length()` a bit more strict by also checking that the input is a vector. R is a bit weird in that it gives a length to pretty much every object, and you can imagine not wanting this code to succeed:
+Let's make `expect_length()` a bit more strict by also checking that the input is a vector. R is a bit unusual in that it gives a length to pretty much every object, and you can imagine not wanting this code to succeed:
 
 ```{r}
 expect_length(mean, 1)
@@ -182,7 +182,7 @@ Note the variety of messages:
 
 * When `object` isn't an object, we only need to say what we expect.
 * When `object` isn't an S3 object, we know it's an S4 object.
-* When `inherits()` is `FALSE`, we provide the actual _class_, since that's most informative.
+* When `inherits()` is `FALSE`, we provide the actual *class*, since that's most informative.
 
 I also check that the `class` argument must be a string. This is an error, not a failure, because it suggests you're using the function incorrectly.
 

vignettes/mocking.Rmd

@@ -20,15 +20,15 @@ snapper$start_file("snapshotting.Rmd", "test")
 Sys.setenv(TESTTHAT_PKG = "testthat")
 ```
 
-Mocking allows you to temporarily replace the implementation of a function with something that makes it easier to test. It's useful when testing failure scenarios that are hard to generate organically (e.g. what happens if dependency X isn't installed?), making tests more reliable by eliminating potential variability, and making tests faster. It's also a general escape hatch to resolve pretty much any challenging testing problem.
+Mocking allows you to temporarily replace the implementation of a function with something that makes it easier to test. It's useful when testing failure scenarios that are hard to generate organically (e.g., what happens if dependency X isn't installed?), making tests more reliable by eliminating potential variability, and making tests faster. It's also a general escape hatch to resolve pretty much any challenging testing problem.
 
-(If, like me, you're confused as to why you'd want to cruelly make fun of your tests, here mocking is used in the sense of making a fake or simulated version of something, i.e. a mock-up.)
+(If, like me, you're confused as to why you'd want to cruelly make fun of your tests, here mocking is used in the sense of making a fake or simulated version of something, i.e., a mock-up.)
 
-testthat supports mocking primarily through `local_mocked_bindings()` for mocking functions, and we'll focus on that function in this vignette. But it also provides other methods for specialised cases: you can use `local_mocked_s3_method()` to mock an S3 method, `local_mocked_s4_method()` to mock a S4 method, and `local_mocked_r6_class()` to mock an R6 class. Once you understand the basic idea of mocking, I think it should be straightforward to apply these other functions where needed.
+testthat supports mocking primarily through `local_mocked_bindings()` for mocking functions, and we'll focus on that function in this vignette. But it also provides other methods for specialized cases: you can use `local_mocked_s3_method()` to mock an S3 method, `local_mocked_s4_method()` to mock an S4 method, and `local_mocked_r6_class()` to mock an R6 class. Once you understand the basic idea of mocking, I think it should be straightforward to apply these other functions where needed.
 
 ## Getting started with mocking
 
-Let's begin by motivating mocking with a simple example. Imagine you're writing a function like `rlang::check_installed()`. The goal of this function is to check if a package is installed, and if not, give a nice error message. It also takes an option `min_version` argument which you can use to enforce a version constraint. A simple base R implementation might look something like this:
+Let's begin by motivating mocking with a simple example. Imagine you're writing a function like `rlang::check_installed()`. The goal of this function is to check if a package is installed, and if not, give a nice error message. It also takes an optional `min_version` argument which you can use to enforce a version constraint. A simple base R implementation might look something like this:
 
 ```{r}
 check_installed <- function(pkg, min_version = NULL) {
@@ -84,13 +84,13 @@ test_that("check_installed() checks minimum version", {
 })
 ```
 
-But it's starting to feel like we've accumulated a bunch of potentially fragile hacks. So let's see how we could make these tests more robust with mocking. First we need to add `requireNamespace` and `packageVersion` bindings in our package. This is needed because `requireNamespace` and `packageVersion` are base functions: 
+But it's starting to feel like we've accumulated a bunch of potentially fragile hacks. So let's see how we could make these tests more robust with mocking. First, we need to add `requireNamespace` and `packageVersion` bindings in our package. This is needed because `requireNamespace` and `packageVersion` are base functions: 
 ```{r}
 requireNamespace <- NULL
 packageVersion <- NULL
 ```
 
-For the first test, we mock `requireNamespace()` twice, first returning `TRUE`, pretending every package is installed, and then returning `FALSE` pretending that no packages are installed.
+For the first test, we mock `requireNamespace()` twice, first returning `TRUE`, pretending every package is installed, and then returning `FALSE`, pretending that no packages are installed.
 
 ```{r}
 test_that("check_installed() checks package is installed", {

vignettes/skipping.Rmd

@@ -20,14 +20,14 @@ Skipping is a relatively advanced topic because in most cases you want all your
 The most common exceptions are:
 
 -   You're testing a web service that occasionally fails, and you don't want to run the tests on CRAN.
-    Or maybe the API requires authentication, and you can only run the tests when you've [securely distributed](https://gargle.r-lib.org/articles/articles/managing-tokens-securely.html) some secrets.
+    Or the API requires authentication, and you can only run the tests when you've [securely distributed](https://gargle.r-lib.org/articles/articles/managing-tokens-securely.html) some secrets.
 
 -   You're relying on features that not all operating systems possess, and want to make sure your code doesn't run on a platform where it doesn't work.
-    This platform tends to be Windows, since amongst other things, it lacks full utf8 support.
+    This platform tends to be Windows, since among other things, it lacks full UTF-8 support.
 
 -   You're writing your tests for multiple versions of R or multiple versions of a dependency and you want to skip when a feature isn't available.
     You generally don't need to skip tests if a suggested package is not installed.
-    This is only needed in exceptional circumstances, e.g. when a package is not available on some operating system.
+    This is only needed in exceptional circumstances, e.g., when a package is not available on some operating system.
 
 ```{r setup}
 library(testthat)
@@ -43,12 +43,12 @@ testthat comes with a variety of helpers for the most common situations:
 -   `skip_on_os()` allows you to skip tests on a specific operating system.
     Generally, you should strive to avoid this as much as possible (so your code works the same on all platforms), but sometimes it's just not possible.
 
--   `skip_on_ci()` skips tests on most continuous integration platforms (e.g. GitHub Actions, Travis, Appveyor).
+-   `skip_on_ci()` skips tests on most continuous integration platforms (e.g., GitHub Actions, Travis, Appveyor).
 
 You can also easily implement your own using either `skip_if()` or `skip_if_not()`, which both take an expression that should yield a single `TRUE` or `FALSE`.
 
 All reporters show which tests are skipped.
-As of testthat 3.0.0, ProgressReporter (used interactively) and CheckReporter (used inside of `R CMD check`) also display a summary of skips across all tests.
+As of testthat 3.0.0, ProgressReporter (used interactively) and CheckReporter (used inside `R CMD check`) also display a summary of skips across all tests.
 It looks something like this:
 
 ```         
@@ -77,7 +77,7 @@ skip_if_dangerous <- function() {
 ## Embedding `skip()` in package functions
 
 Another potentially useful technique is to build a `skip()` directly into a package function.
-For example, take a look at [`pkgdown:::convert_markdown_to_html()`](https://github.com/r-lib/pkgdown/blob/v2.0.7/R/markdown.R#L95-L106), which absolutely, positively cannot work if the Pandoc tool is unavailable:
+For example, take a look at [`pkgdown:::convert_markdown_to_html()`](https://github.com/r-lib/pkgdown/blob/v2.0.7/R/markdown.R#L95-L106), which absolutely cannot work if the Pandoc tool is unavailable:
 
 ```{r eval = FALSE}
 convert_markdown_to_html <- function(in_path, out_path, ...) {

vignettes/snapshotting.Rmd

@@ -16,16 +16,16 @@ set.seed(1014)
 ```
 
 The goal of a unit test is to record the expected output of a function using code.
-This is a powerful technique because not only does it ensure that code doesn't change unexpectedly, it also expresses the desired behaviour in a way that a human can understand.
+This is a powerful technique because not only does it ensure that code doesn't change unexpectedly, but it also expresses the desired behavior in a way that a human can understand.
 
-However, it's not always convenient to record the expected behaviour with code.
+However, it's not always convenient to record the expected behavior with code.
 Some challenges include:
 
 -   Text output that includes many characters like quotes and newlines that require special handling in a string.
 
 -   Output that is large, making it painful to define the reference output and bloating the size of the test file.
 
--   Binary formats like plots or images, which are very difficult to describe in code: e.g. the plot looks right, the error message is actionable, or the print method uses colour effectively.
+-   Binary formats like plots or images, which are very difficult to describe in code: e.g., the plot looks right, the error message is actionable, or the print method uses colour effectively.
 
 For these situations, testthat provides an alternative mechanism: snapshot tests.
 Instead of using code to describe expected output, snapshot tests (also known as [golden tests](https://ro-che.info/articles/2017-12-04-golden-tests)) record results in a separate human readable file.
@@ -91,7 +91,7 @@ snapper$start_file("snapshotting.Rmd", "test")
 
 When we run the test for the first time, it automatically generates reference output, and prints it, so that you can visually confirm that it's correct.
 The output is automatically saved in `_snaps/{name}.md`.
-The name of the snapshot matches your test file name --- e.g. if your test is `test-pizza.R` then your snapshot will be saved in `test/testthat/_snaps/pizza.md`.
+The name of the snapshot matches your test file name --- e.g. if your test is `test-pizza.R` then your snapshot will be saved in `tests/testthat/_snaps/pizza.md`.
 As the file name suggests, this is a markdown file, which I'll explain shortly.
 
 If you run the test again, it'll succeed:

vignettes/test-fixtures.Rmd

@@ -20,7 +20,7 @@ knitr::opts_chunk$set(
 >
 > ― Chief Si'ahl
 
-Ideally, a test should leave the world exactly as it found it. But you often need to make some changes in order to exercise every part of your code:
+Ideally, a test should leave the world exactly as it found it. But you often need to make some changes to exercise every part of your code:
 
 -   Create a file or directory
 -   Create a resource on an external system
@@ -31,9 +31,9 @@ Ideally, a test should leave the world exactly as it found it. But you often nee
 
 How can you clean up these changes to get back to a clean slate? Scrupulous attention to cleanup is more than just courtesy or being fastidious. It is also self-serving. The state of the world after test `i` is the starting state for test `i + 1`. Tests that change state willy-nilly eventually end up interfering with each other in ways that can be very difficult to debug.
 
-Most tests are written with an implicit assumption about the starting state, usually whatever *tabula rasa* means for the target domain of your package. If you accumulate enough sloppy tests, you will eventually find yourself asking the programming equivalent of questions like "Who forgot to turn off the oven?" and "Who didn't clean up after the dog?". (If you've got yourself into this state, testthat provides another tool to help you figure out exactly what test is to blame: `set_state_inspector()`.)
+Most tests are written with an implicit assumption about the starting state, usually whatever *tabula rasa* means for the target domain of your package. If you accumulate enough sloppy tests, you will eventually find yourself asking the programming equivalent of questions like "Who forgot to turn off the oven?" and "Who didn't clean up after the dog?" (If you've got yourself into this state, testthat provides another tool to help you figure out exactly what test is to blame: `set_state_inspector()`.)
 
-It's also important that your setup and cleanup is easy to use when working interactively. When a test fails, you want to be able to quickly recreate the exact environment in which the test is run so you can interactively experiment to figure out what went wrong.
+It's also important that your setup and cleanup are easy to use when working interactively. When a test fails, you want to be able to quickly recreate the exact environment in which the test is run so you can interactively experiment to figure out what went wrong.
 
 This article introduces a powerful technique that allows you to solve both problems: **test fixtures**. We'll begin by discussing some pre-existing tools, then learn about the tools that make fixtures possible, talk about exactly what a test fixture is, and show a few examples.
 
@@ -45,7 +45,7 @@ library(testthat)
 
 ## `local_` helpers
 
-We'll begin by giving you the bare minimum of knowledge to change global state _just_ within your test. The withr package provides a number of functions that temporarily change the state of the world, carefully undoing the changes when the current function finishes:
+We'll begin by giving you the bare minimum of knowledge to change global state *just* within your test. The withr package provides a number of functions that temporarily change the state of the world, carefully undoing the changes when the current function finishes:
 
 | Do / undo this              | withr function    |
 |-----------------------------|-------------------|
@@ -57,7 +57,7 @@ We'll begin by giving you the bare minimum of knowledge to change global state _
 
 (You can see a full list at <https://withr.r-lib.org/> but these five are by far the most commonly used.)
 
-These allow you to control options that would otherwise be painful. For example, imagine you were testing the base R code that rounds numbers to a fixed number of places when printing. You could write code like this:
+These allow you to control options that would otherwise be painful. For example, imagine you were testing base R code that rounds numbers to a fixed number of places when printing. You could write code like this:
 
 ```{r}
 test_that("print() respects digits option", {
@@ -202,7 +202,7 @@ neater <- function(x, sig_digits) {
 neater(pi)
 ```
 
-This code doesn't work because the cleanup happens too soon, when `local_digits()` exits, not when `neat()` finishes.
+This code doesn't work because the cleanup happens too soon, when `local_digits()` exits, not when `neater()` finishes.
 
 Fortunately, `withr::defer()` allows us to solve this problem by providing an `envir` argument that allows you to control when cleanup occurs. The exact details of how this works are rather complicated, but fortunately there's a common pattern you can use without understanding all the details. Your helper function should always have an `env` argument that defaults to `parent.frame()`, which you pass to the second argument of `defer()`: