Merge commit '3c45e5cbf2f4852fa5381b0a18a9a75753d1be24'

Author: hadley

NAMESPACE

@@ -145,16 +145,13 @@ export(is.expectation)
 export(is_a)
 export(is_checking)
 export(is_equivalent_to)
-export(is_false)
 export(is_identical_to)
 export(is_informative_error)
 export(is_less_than)
 export(is_more_than)
-export(is_null)
 export(is_parallel)
 export(is_snapshot)
 export(is_testing)
-export(is_true)
 export(it)
 export(local_edition)
 export(local_mock)
@@ -164,10 +161,10 @@ export(local_snapshotter)
 export(local_test_context)
 export(local_test_directory)
 export(make_expectation)
-export(matches)
 export(mock_output_sequence)
 export(new_expectation)
 export(not)
+export(pass)
 export(prints_text)
 export(quasi_label)
 export(run_cpp_tests)

NEWS.md

@@ -1,6 +1,9 @@
 # testthat (development version)
 
 * `expect_no_failures()` and `expect_no_succeses()` are now deprecated as `expect_success()` now test for no failures and `expect_failure()` tests for no successes (#)
+* 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).
 * testthat now requires R 4.1.
 * `expect_s4_class()` now supports unquoting (@stibu81, #2064).

R/expect-constant.R

@@ -7,7 +7,6 @@
 #'
 #' Attributes are ignored.
 #'
-#' @seealso [is_false()] for complement
 #' @inheritParams expect_that
 #' @family expectations
 #' @examples

R/expect-self-test.R

@@ -165,7 +165,7 @@ expect_snapshot_reporter <- function(
   paths = test_path("reporters/tests.R")
 ) {
   local_options(rlang_trace_format_srcrefs = FALSE)
-  local_rng_version("3.3")
+  withr::local_rng_version("3.3")
   set.seed(1014)
   # withr::local_seed(1014)
 
@@ -178,12 +178,6 @@ expect_snapshot_reporter <- function(
   )
 }
 
-# to work around https://github.com/r-lib/withr/issues/167
-local_rng_version <- function(version, .local_envir = parent.frame()) {
-  withr::defer(RNGversion(as.character(getRversion())), envir = .local_envir)
-  suppressWarnings(RNGversion(version))
-}
-
 # Use specifically for testthat tests in order to override the
 # defaults found when starting the reporter
 local_output_override <- function(

R/expect-that.R

@@ -36,14 +36,24 @@ 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
+#' @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 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.
 #' @export
 #' @examples
 #' \dontrun{
@@ -53,39 +63,41 @@ expect_that <- function(object, condition, info = NULL, label = NULL) {
 fail <- function(
   message = "Failure has been forced",
   info = NULL,
-  trace_env = caller_env()
+  srcref = NULL,
+  trace_env = caller_env(),
+  trace = NULL
 ) {
-  expect(FALSE, message, info = info, trace_env = trace_env)
+  if (is.null(trace)) {
+    trace <- trace_back(top = getOption("testthat_topenv"), bottom = trace_env)
+  }
+  # Only show if there's at least one function apart from the expectation
+  if (trace_length(trace) <= 1) {
+    trace <- NULL
+  }
+
+  message <- paste(c(message, info), collapse = "\n")
+  expectation("failure", message, srcref = srcref, trace = trace)
 }
 
 #' @rdname fail
+#' @param value Value to return, typically the result of evaluating the
+#'   `object` argument to the expectation.
 #' @export
-succeed <- function(message = "Success has been forced", info = NULL) {
-  expect(TRUE, message, info = info)
+pass <- function(value) {
+  expectation("success", "success")
+  invisible(value)
 }
 
-#' Negate an expectation
+#' Mark a test as successful
 #'
-#' This negates an expectation, making it possible to express that you
-#' want the opposite of a standard expectation. This function is deprecated
-#' and will be removed in a future version.
+#' This is an older version of [pass()] that exists for backwards compatibility.
+#' You should now use `pass()` instead`
 #'
-#' @param f an existing expectation function
-#' @keywords internal
 #' @export
-not <- function(f) {
-  warning("`not()` is deprecated.", call. = FALSE)
-  stopifnot(is.function(f))
-
-  negate <- function(expt) {
-    expect(
-      !expectation_success(expt),
-      failure_message = paste0("NOT(", expt$message, ")"),
-      srcref = expt$srcref
-    )
-  }
+#' @inheritParams fail
+#' @keywords internal
+succeed <- function(message = "Success has been forced", info = NULL) {
+  message <- paste(c(message, info), collapse = "\n")
 
-  function(...) {
-    negate(capture_expectation(f(...)))
-  }
+  expectation("success", message)
 }

R/expectation.R

@@ -5,34 +5,9 @@
 #'
 #' @param ok `TRUE` or `FALSE` indicating if the expectation was successful.
 #' @param failure_message Message to show if the expectation failed.
-#' @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 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.
-#' @return An expectation object. Signals the expectation condition
+#' @inheritParams fail
+#' @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(
@@ -43,58 +18,39 @@ expect <- function(
   trace = NULL,
   trace_env = caller_env()
 ) {
-  type <- if (ok) "success" else "failure"
-
-  # Preserve existing API which appear to be used in package test code
-  # Can remove in next major release
-  if (missing(failure_message)) {
-    warn("`failure_message` is missing, with no default.")
-    message <- "unknown failure"
+  if (ok) {
+    succeed(failure_message)
   } else {
-    # A few packages include code in info that errors on evaluation
-    if (ok) {
-      message <- paste(failure_message, collapse = "\n")
-    } else {
-      message <- paste(c(failure_message, info), collapse = "\n")
-    }
-  }
-
-  if (!ok) {
-    if (is.null(trace)) {
-      trace <- trace_back(
-        top = getOption("testthat_topenv"),
-        bottom = trace_env
-      )
-    }
-
-    # Only show if there's at least one function apart from the expectation
-    if (trace_length(trace) <= 1) {
-      trace <- NULL
-    }
+    fail(
+      failure_message,
+      info,
+      srcref = srcref,
+      trace = trace,
+      trace_env = trace_env
+    )
   }
-
-  exp <- expectation(type, message, srcref = srcref, trace = trace)
-  exp_signal(exp)
 }
 
-
 #' Construct an expectation object
 #'
+#' @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.
 #'
-#' Create an expectation with `expectation()` or `new_expectation()`
-#' and signal it with `exp_signal()`.
+#' `new_expectation()` creates an expectation object and `exp_signal()` signals
+#' it. `expectation()` does both.
 #'
 #' @param type Expectation type. Must be one of "success", "failure", "error",
 #'   "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) {
-  new_expectation(type, message, srcref = srcref, trace = trace)
+  exp <- new_expectation(type, message, srcref = srcref, trace = trace)
+  exp_signal(exp)
 }
 #' @rdname expectation
 #' @param ... Additional attributes for the expectation object.
@@ -207,7 +163,7 @@ as.expectation.error <- function(x, srcref = NULL) {
     cnd_message(x)
   )
 
-  expectation("error", msg, srcref, trace = x[["trace"]])
+  new_expectation("error", msg, srcref = srcref, trace = x[["trace"]])
 }
 
 
@@ -217,12 +173,17 @@ is_simple_error <- function(x) {
 
 #' @export
 as.expectation.warning <- function(x, srcref = NULL) {
-  expectation("warning", cnd_message(x), srcref, trace = x[["trace"]])
+  new_expectation(
+    "warning",
+    cnd_message(x),
+    srcref = srcref,
+    trace = x[["trace"]]
+  )
 }
 
 #' @export
 as.expectation.skip <- function(x, ..., srcref = NULL) {
-  expectation("skip", cnd_message(x), srcref, trace = x[["trace"]])
+  new_expectation("skip", cnd_message(x), srcref = srcref, trace = x[["trace"]])
 }
 
 #' @export