Polish vignette + docs

Author: hadley

R/expect-that.R

@@ -2,25 +2,37 @@
 #'
 #' @description
 #' These are the primitives that you can use to implement your own expectations.
-#' Every branch of code inside an expectation must call either `pass()` or
-#' `fail()`; learn more in `vignette("custom-expectation")`.
+#' Regardless of how it's called an expectation should either return `pass()`,
+#' `fail()`, or throw an error (if for example, the arguments are invalid).
 #'
-#' @param message a string to display.
+#' Learn more about creating your own expectations in
+#' `vignette("custom-expectation")`.
+#'
+#' @param message Failure message to send to the user. It's best practice to
+#'   describe both what is expected and what was actually received.
 #' @param info Character vector continuing additional information. Included
 #'   for backward compatibility only and new expectations should not use it.
 #' @param srcref Location of the failure. Should only needed to be explicitly
 #'   supplied when you need to forward a srcref captured elsewhere.
+#' @param trace_env If `trace` is not specified, this is used to generate an
+#'   informative traceack for failures. You should only need to set this if
+#'   you're calling `fail()` from a helper function; see
+#'   `vignette("custom-expectation")` for details.
 #' @param trace An optional backtrace created by [rlang::trace_back()].
 #'   When supplied, the expectation is displayed with the backtrace.
-#' @param trace_env If `is.null(trace)`, this is used to automatically
-#'   generate a traceback running from `test_code()`/`test_file()` to
-#'   `trace_env`. You'll generally only need to set this if you're wrapping
-#'   an expectation inside another function.
+#'   Expert use only.
 #' @export
 #' @examples
-#' \dontrun{
-#' test_that("this test fails", fail())
-#' test_that("this test succeeds", succeed())
+#' expect_length <- function(object, n) {
+#'   act <- quasi_label(rlang::enquo(object), arg = "object")
+#'
+#'   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))
+#'   }
+#'
+#'   pass(act$val)
 #' }
 fail <- function(
   message = "Failure has been forced",
@@ -53,7 +65,7 @@ pass <- function(value) {
 #' Mark a test as successful
 #'
 #' This is an older version of [pass()] that exists for backwards compatibility.
-#' You should now use `pass()` instead`
+#' You should now use `pass()` instead.
 #'
 #' @export
 #' @inheritParams fail

man/expect.Rd

@@ -160,56 +160,25 @@ expect_s3_class(x3, "integer")
 
 ## Repeated code
 
-As you write more expectations, you might discover repeated code that you want to extract out in to a helper. For example, testthat has `expect_true()`, `expect_false()`, and `expect_null()` which are special cases of `expect_equal()`. 
+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.
 
-```{r}
-expect_true <- function(object) {
-  act <- quasi_label(enquo(object))
-  expect_waldo_equal_("equal", act, TRUE, ignore_attr = TRUE)
-}
-expect_false <- function(object) {
-  act <- quasi_label(enquo(object))
-  expect_waldo_equal_("equal", act, FALSE, ignore_attr = TRUE)
-}
-expect_null <- function(object, label = NULL) {
-  act <- quasi_label(enquo(object))
-  expect_waldo_equal_("equal", act, NULL)
-}
-```
-
-You might wonder why these functions don't call `expect_equal()` directly. Unfortunately creating helper functions is not straightforward in testthat because every `fail()` captures the calling environment in order to give maximally useful tracebacks. Getting this right is not critical (you'll just get a slightly suboptimal traceback in the case of failure) but it's good practice, particularly for testthat itself.
-
-To do things 100% correctly, in your helper function you need to have a `trace_env` argument that defaults to `caller_env()`, and then you need to pass it to every instance of 
+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:
 
 ```{r}
-expect_waldo_equal_ <- function(
-  type,
-  act,
-  exp,
-  info,
-  ...,
-  trace_env = caller_env()
-) {
-  comp <- waldo_compare(
-    act$val,
-    exp$val,
-    ...,
-    x_arg = "actual",
-    y_arg = "expected"
-  )
-  if (length(comp) != 0) {
-    msg <- sprintf(
-      "%s (%s) not %s to %s (%s).\n\n%s",
-      act$lab,
-      "`actual`",
-      type,
-      exp$lab,
-      "`expected`",
-      paste0(comp, collapse = "\n\n")
-    )
-    return(fail(msg, info = info, trace_env = trace_env))
+expect_length_ <- function(act, n, trace_env = caller_env()) {
+  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, trace_env = trace_env))
   }
+
   pass(act$val)
 }
 
+expect_length <- function(object, n) {  
+  act <- quasi_label(rlang::enquo(object), arg = "object")
+  expect_length_(act, n)
+}
 ```
+
+Note that the helper probably shouldn't be user facing, and we give it a `_` suffix to make that clear. It's also typically easiest for a helper to take the labelled value produced by `quasi_label()` rather than having to do that repeatedly.