Use in the vignette; update examples

hadley · hadley · commit 06aa28cc6210 · 2025-07-28T13:16:19.000-05:00
And add a test
diff --git a/NAMESPACE b/NAMESPACE
@@ -164,6 +164,7 @@ export(make_expectation)
 export(mock_output_sequence)
 export(new_expectation)
 export(not)
+export(pass)
 export(prints_text)
 export(quasi_label)
 export(run_cpp_tests)
diff --git a/NEWS.md b/NEWS.md
@@ -1,5 +1,6 @@
 # testthat (development version)
 
+* New `pass()` function to use in place of `succeed()` (#2113).
 * `expectation()` is now a combination of `new_expectation()` and `exp_signal()` (#2125).
 * `is_null()`/`matches()` deprecated in 2.0.0 (2017-12-19) and `is_true()`/`is_false()` deprecated in 2.1.0 (2019-04-23) have been removed (#2109).
 * `local_edition()` now gives a useful error for bad values (#1547).
diff --git a/R/expect-that.R b/R/expect-that.R
@@ -36,11 +36,12 @@ expect_that <- function(object, condition, info = NULL, label = NULL) {
   condition(object)
 }
 
-#' Default expectations that always succeed or fail.
+#' `pass()` or `fail()` a test
 #'
-#' These allow you to manually trigger success or failure. Failure is
-#' particularly useful to a pre-condition or mark a test as not yet
-#' implemented.
+#' @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")`.
 #'
 #' @param message a string to display.
 #' @inheritParams expect
@@ -71,6 +72,19 @@ fail <- function(
 
 #' @rdname fail
 #' @export
+pass <- function(value) {
+  expectation("success", "success")
+  invisible(value)
+}
+
+#' Mark a test as successful
+#'
+#' This is an older version of [pass()] that exists for backwards compatibility.
+#' You should now use `pass()` instead`
+#'
+#' @export
+#' @inheritParams fail
+#' @keywords internal
 succeed <- function(message = "Success has been forced", info = NULL) {
   message <- paste(c(message, info), collapse = "\n")
 
diff --git a/R/expectation.R b/R/expectation.R
@@ -15,24 +15,8 @@
 #'   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.
-#' @return An expectation object. Signals the expectation condition
+#' @return An expectation object from either `succeed()` or `fail()`.
 #'   with a `continue_test` restart.
-#'
-#' @details
-#'
-#' While `expect()` creates and signals an expectation in one go,
-#' `exp_signal()` separately signals an expectation that you
-#' have manually created with [new_expectation()]. Expectations are
-#' signalled with the following protocol:
-#'
-#' * If the expectation is a failure or an error, it is signalled with
-#'   [base::stop()]. Otherwise, it is signalled with
-#'   [base::signalCondition()].
-#'
-#' * The `continue_test` restart is registered. When invoked, failing
-#'   expectations are ignored and normal control flow is resumed to
-#'   run the other tests.
-#'
 #' @seealso [exp_signal()]
 #' @export
 expect <- function(
@@ -60,7 +44,7 @@ expect <- function(
 #'
 #' @description
 #' For advanced use only. If you are creating your own expectation, you should
-#' call [expect()] instead. See `vignette("custom-expectation")` for more
+#' call [pass()] or [fail()]. See `vignette("custom-expectation")` for more
 #' details.
 #'
 #' `new_expectation()` creates an expectation object and `exp_signal()` signals
@@ -70,6 +54,7 @@ expect <- function(
 #'   "skip", "warning".
 #' @param message Message describing test failure
 #' @param srcref Optional `srcref` giving location of test.
+#' @keywords internal
 #' @inheritParams expect
 #' @export
 expectation <- function(type, message, srcref = NULL, trace = NULL) {
diff --git a/_pkgdown.yml b/_pkgdown.yml
@@ -78,7 +78,6 @@ reference:
 - title: Expectation internals
   contents:
   - expect
-  - expectation
   - fail
   - expect_success
 
diff --git a/man/expect.Rd b/man/expect.Rd
diff --git a/man/expectation.Rd b/man/expectation.Rd
diff --git a/man/fail.Rd b/man/fail.Rd
diff --git a/man/succeed.Rd b/man/succeed.Rd
diff --git a/tests/testthat/test-expect-that.R b/tests/testthat/test-expect-that.R
@@ -0,0 +1,5 @@
+test_that("pass() succeeds and returns value", {
+  expect_success(pass("x"))
+  expect_invisible(pass("x"))
+  expect_equal(pass("x"), "x")
+})
diff --git a/vignettes/.gitignore b/vignettes/.gitignore
@@ -1,2 +1,4 @@
 *.html
 *.R
+
+/.quarto/
diff --git a/vignettes/custom-expectation.Rmd b/vignettes/custom-expectation.Rmd
@@ -12,77 +12,69 @@ library(testthat)
 knitr::opts_chunk$set(collapse = TRUE, comment = "#>")
 ```
 
-This vignette shows you how to create custom expectations that work identically to the built-in `expect_` functions. Since these functions will need to be loaded in order for your tests to work, we recommend putting them in an appropriately named helper file, i.e. `tests/testthat/helper-expectations.R`.
+This vignette shows you how to write your expectations that work identically to the built-in `expect_` functions. 
+
+You can use these either locally by putting them in a helper file, or export them from your package.
 
 ## Expectation basics
 
 There are three main parts to writing an expectation, as illustrated by `expect_length()`:
 
 ```{r}
-expect_length <- function(object, n) {
+expect_length <- function(object, n) {  
   # 1. Capture object and label
   act <- quasi_label(rlang::enquo(object), arg = "object")
 
-  # 2. Call expect()
-  act$n <- length(act$val)
-  expect(
-    act$n == n,
-    sprintf("%s has length %i, not length %i.", act$lab, act$n, n)
-  )
-
-  # 3. Invisibly return the value
-  invisible(act$val)
+  # 2. Verify the expectations
+  act_n <- length(act$val)
+  if (act_n != n) {
+    msg <- sprintf("%s has length %i, not length %i.", act$lab, act_n, n)
+    fail(msg)
+  }
+  
+  # 3. Pass
+  pass(act$val)
 }
 ```
 
-### Quasi-labelling
+### Capture value and label
 
 The first step in any expectation is to capture the actual object, and generate a label for it to use if a failure occur. All testthat expectations support quasiquotation so that you can unquote variables. This makes it easier to generate good labels when the expectation is called from a function or within a for loop.
 
-By convention, the first argument to every `expect_` function is called `object`, and you capture it's value (`val`) and label (`lab`) with `act <- quasi_label(enquo(object))`, where `act` is short for actual.
+By convention, the first argument to every `expect_` function is called `object`, and you capture its value (`val`) and label (`lab`) with `act <- quasi_label(enquo(object))`, where `act` is short for actual (in constrast to expected).
 
 ### Verify the expectation
 
-Next, you should verify the expectation. This often involves a little computation (here just figuring out the `length`), and you should typically store the results back into the `act` object.
+Now we can check if our expectation is met and call `fail()` if not. The most challenging job here is typically generating the error message because you want it to be as self-contained as possible. This means it should typically give both the expected and actual value, along with the name of the object passed to the expectation. testthat expectations use `sprintf()`, but if you're familiar with {glue}, you might want to use that instead.
 
-Next you call `expect()`. This has two arguments:
+More complicated expectations will have more `if` statements. For example, we might want to make our `expect_length()` function include an assertion that `object` is a vector:
+
+```{r}
+expect_vector_length <- function(object, n) {  
+  act <- quasi_label(rlang::enquo(object), arg = "object")
 
-1.  `ok`: was the expectation successful? This is usually easy to write
+  if (!is.atomic(act$val) || !is.list(act$val)) {
+    msg <- sprintf("%s is a %s, not a vector", act$lab, typeof(act$val))
+    fail(msg)
+  }
 
-2.  `failure_message`: What informative error message should be reported to
-    the user so that they can diagnose the problem. This is often hard to 
-    write!
-    
-    For historical reasons, most built-in expectations generate these with
-    `sprintf()`, but today I'd recommend using the 
-    [glue](https://glue.tidyverse.org) package
+  act_n <- length(act$val)
+  if (act$n != n) {
+    msg <- sprintf("%s has length %i, not length %i.", act$lab, act_n, n)
+    fail(msg)
+  }
+  
+  pass(act$val)
+}
+```
 
-### Invisibly return the input
+### Pass the test
 
-Expectation functions are called primarily for their side-effects (triggering a failure), so should invisibly return their input, `act$val`. This allows expectations to be chained:
+If no assertions fail, call `pass()` with the input value (usually `act$val`). Returning the input value is good practice since expectation functions are called primarily for their side-effects (triggering a failure). This allows expectations to be chained:
 
 ```{r}
 mtcars |>
   expect_type("list") |>
   expect_s3_class("data.frame") |> 
   expect_length(11)
 ```
-
-## `succeed()` and `fail()`
-
-For expectations with more complex logic governing when success or failure occurs, you can use `succeed()` and `fail()`. These are simple wrappers around `expect()` that allow you to write code that looks like this:
-
-```{r}
-expect_length <- function(object, n) {
-  act <- quasi_label(rlang::enquo(object), arg = "object")
-
-  act$n <- length(act$val)
-  if (act$n == n) {
-    succeed()
-    return(invisible(act$val))
-  }
-
-  message <- sprintf("%s has length %i, not length %i.", act$lab, act$n, n)
-  fail(message)
-}
-```
