% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/testit.R
\name{assert}
\alias{assert}
\alias{\%==\%}
\title{Assert that conditions are true, with an informative failure message}
\usage{
assert(fact, ...)

x \%==\% y
}
\arguments{
\item{fact}{A character string describing what is being tested. This message
is shown when an assertion fails, so make it descriptive (e.g., \code{'log() returns correct values'}). If \code{fact} is not a character string, it is
treated as a test expression (i.e., the message is optional).}

\item{...}{An R expression wrapped in \code{{}}; see Details.}

\item{x, y}{Two R objects to be compared for identity.}
}
\value{
Invisible \code{NULL} if all conditions pass. If any condition fails, an
error is signaled that includes the \code{fact} message and the expression that
failed. For \verb{\%==\%}, \code{TRUE} or \code{FALSE}.
}
\description{
Test that one or more conditions are \code{TRUE}. If any condition fails, an error
is raised with the \code{fact} message, making it easy to identify which test
failed and why. This is the primary function for writing tests with
\strong{testit}.

The infix operator \verb{\%==\%} is a shortcut for \code{\link[=identical]{identical()}} that
provides helpful diagnostics on failure. \code{x \%==\% y} returns \code{TRUE} if \code{x}
and \code{y} are identical, and \code{FALSE} otherwise. When used inside \code{assert()},
a failing \verb{\%==\%} comparison will display both values via \code{\link[=str]{str()}} so you can
see exactly what differed.
}
\details{
The recommended usage is to pass a single expression wrapped in \code{{}} as the
second argument. Inside \code{{}}, any \strong{statement-level} sub-expression wrapped
in parentheses \verb{()} is treated as a test condition -- its value is checked
and must be \code{TRUE}. Parentheses used for grouping within a larger expression
(e.g., \code{(a + b) * c}) are not checked. Sub-expressions \emph{without} parentheses
are ordinary R code (e.g., variable assignments or setup steps) and are never
checked.

\verb{()} tests work inside \code{if}, \code{for}, \code{while}, and \code{repeat} bodies. Internally,
\code{assert()} walks the expression tree and transforms statement-level \verb{()} into
checks before evaluating the entire block in one frame (so \code{on.exit()} works
as expected).
}
\note{
Key differences from \code{\link[=stopifnot]{stopifnot()}}:
\itemize{
\item \code{assert()} shows your custom \code{fact} message on failure, making errors
easier to diagnose.
\item \code{logical(0)} (empty logical) is treated as a failure, not a pass.
\item All conditions are evaluated even if earlier ones fail; all failures are
reported together in a single error message.
}
}
\examples{
library(testit)
assert('T is bad for TRUE, and so is F for FALSE', {
  T = FALSE; F = TRUE
  (T != TRUE)  # note the parentheses
  (F != FALSE)
})

assert('A Poisson random number is non-negative', {
  x = rpois(1, 10)
  (x >= 0)
  (x > -1)
})

# () works inside control structures too
assert('conditional test', {
  if (requireNamespace('base', quietly = TRUE)) (1 + 1 == 2)
})
}
