✨ Proofreading ✨

Author: hadley

vignettes/custom-expectation.Rmd

@@ -11,12 +11,12 @@ vignette: >
 library(testthat)
 knitr::opts_chunk$set(collapse = TRUE, comment = "#>")
 
-# Pretend we're snapsotting
+# Pretend we're snapshotting
 snapper <- local_snapshotter(fail_on_new = FALSE)
 snapper$start_file("snapshotting.Rmd", "test")
 ```
 
-This vignette shows you how to write your expectations. You can use within your package by putting them in a helper file, or share them with others by exporting them from your package.
+This vignette shows you how to write your own expectations. You can use them within your package by putting them in a helper file, or share them with others by exporting them from your package.
 
 ## Expectation basics
 
@@ -27,21 +27,21 @@ expect_length <- function(object, n) {
   # 1. Capture object and label
   act <- quasi_label(rlang::enquo(object))
 
-  # 2. Fail when expectations aren't met
+  # 2. Check if expectations are violated
   act_n <- length(act$val)
   if (act_n != n) {
     msg <- sprintf("%s has length %i, not length %i.", act$lab, act_n, n)
     return(fail(msg))
   }
   
-  # 3. Pass when expectations are
+  # 3. Pass when expectations are met
   pass(act$val)
 }
 ```
 
-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, 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 the more complicated cases that you'll see later 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 state both what the object is and what you expected.
+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 state both what the object is and what you expected.
 
 Also note that you need to use `return(fail())` here. You won't see the problem when interactively testing your function because when run outside of `test_that()`, `fail()` throws an error, causing the function to terminate early. When running inside of `test_that()`, however, `fail()` does not stop execution because we want to collect all failures in a given test.  
 
@@ -83,7 +83,7 @@ The following sections show you a few more variations, loosely based on existing
 
 ### `expect_vector_length()`
 
-Lets make `expect_length()` a bit more strict by also checking that the input is a vector. R is a bit weird 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 weird 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)
@@ -120,7 +120,7 @@ expect_vector_length(mtcars, 15)
 
 ### `expect_s3_class()`
 
-Or imagine if you're checking to see if an object inherits from an S3 class. In R, there's no direct way to tell if an object is an S3 object: you can confirm that it's an object, then that it's not an S4 object. So you might organise your expectation this way:
+Or imagine if you're checking to see if an object inherits from an S3 class. In R, there's no direct way to tell if an object is an S3 object: you can confirm that it's an object, then that it's not an S4 object. So you might organize your expectation this way:
 
 ```{r}
 expect_s3_class <- function(object, class) {
@@ -174,7 +174,7 @@ expect_s3_class(x1, 1)
 
 ## Repeated code
 
-As you write more expectations, you might discover repeated code that you want to extract out in to a helper. Unfortunately creating helper functions is not straightforward in testthat because every `fail()` captures the calling environment in order to give maximally useful tracebacks. Because getting this right is not critical (you'll just get a slightly suboptimal traceback in the case of failure), we don't recommend bothering. However, we document it here because it's important to get it right in testthat itself.
+As you write more expectations, you might discover repeated code that you want to extract out into a helper. Unfortunately, creating helper functions is not straightforward in testthat because every `fail()` captures the calling environment in order to give maximally useful tracebacks. Because getting this right is not critical (you'll just get a slightly suboptimal traceback in the case of failure), we don't recommend bothering. However, we document it here because it's important to get it right in testthat itself.
 
 The key challenge is that `fail()` captures a `trace_env` which should be the execution environment of the expectation. This usually works, because the default value of `trace_env` is `caller_env()`. But when you introduce a helper, you'll need to explicitly pass it along: