Update custom expectations vignette.

Author: hadley

vignettes/custom-expectation.Rmd

@@ -30,7 +30,10 @@ expect_length <- function(object, n) {
   # 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)
+    msg <- c(
+      sprintf("Expected %s to have length %i.", act$lab, n),
+      sprintf("Actual length: %i.", act$n)
+    )
     return(fail(msg))
   }
   
@@ -41,7 +44,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 🙂.
 
-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.
+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.
 
 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.  
 
@@ -98,13 +101,19 @@ expect_vector_length <- function(object, n) {
   # It's non-trivial to check if an object is a vector in base R so we
   # use an rlang helper
   if (!rlang::is_vector(act$val)) {
-    msg <- sprintf("%s is a %s, not a vector", act$lab, typeof(act$val))
+    msg <- c(
+      sprintf("Expected %s to be a vector", act$lab),
+      sprintf("Actual: %s", typeof(act$val))
+    )
     return(fail(msg))
   }
 
   act_n <- length(act$val)
   if (act_n != n) {
-    msg <- sprintf("%s has length %i, not length %i.", act$lab, act_n, n)
+    msg <- c(
+      sprintf("Expected %s to have length %i.", act$lab, n),
+      sprintf("Actual length: %i.", act_n)
+    )
     return(fail(msg))
   }
   
@@ -131,19 +140,22 @@ expect_s3_class <- function(object, class) {
   act <- quasi_label(rlang::enquo(object))
 
   if (!is.object(act$val)) {
-    return(fail(sprintf("%s is not an object.", act$lab)))
+    msg <- sprintf("Expected %s to be an object.", act$lab)
+    return(fail(msg))
   }
 
   if (isS4(act$val)) {
-    return(fail(sprintf("%s is an S4 object, not an S3 object.", act$lab)))
+    msg <- c(
+      sprintf("Expected %s to be an S3 object.", act$lab),
+      "Actual: S4 object"
+    )
+    return(fail(msg))
   }
 
   if (!inherits(act$val, class)) {
-    msg <- sprintf(
-      "%s inherits from %s not %s.",
-      act$lab,
-      paste0(class(object), collapse = "/"),
-      paste0(class, collapse = "/")
+    msg <- c(
+      sprintf("Expected %s to inherit from %s.", act$lab, class),
+      sprintf("Actual class: %s", class(act$val))
     )
     return(fail(msg))
   }
@@ -165,7 +177,13 @@ expect_s3_class(x3, "integer")
 expect_s3_class(x3, "factor")
 ```
 
-Note that 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.
+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.
+
+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.
 
 ```{r}
 #| error: true