Declare that an expectation either passes or fails

These are the primitives that you can use to implement your own expectations. Regardless of how it's called an expectation should either return pass(), fail(), or throw an error (if for example, the arguments are invalid).

Learn more about creating your own expectations in vignette("custom-expectation").

Usage

fail(
  message = "Failure has been forced",
  info = NULL,
  srcref = NULL,
  trace_env = caller_env(),
  trace = NULL
)

pass(value)

Arguments

message: Failure message to send to the user. It's best practice to describe both what is expected and what was actually received.
info: Character vector continuing additional information. Included for backward compatibility only and new expectations should not use it.
srcref: Location of the failure. Should only needed to be explicitly supplied when you need to forward a srcref captured elsewhere.
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.
trace: An optional backtrace created by rlang::trace_back(). When supplied, the expectation is displayed with the backtrace. Expert use only.
value: Value to return, typically the result of evaluating the object argument to the expectation.

Examples

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)
}