testit (version 0.11)

assert: Assertions with an optional message

Description

The function assert() was inspired by stopifnot(). It emits a message in case of errors, which can be a helpful hint for diagnosing the errors (stopifnot() only prints the possibly truncated source code of the expressions).

The infix operator %==% is simply an alias of the identical() function to make it slightly easier and intuitive to write test conditions. x %==% y is the same as identical(x, y). When it is used inside assert(), a message will be printed if the returned value is not TRUE, to show the values of the LHS (x) and RHS (y) via str(), which can be helpful for you to check why the assertion failed.

Usage

assert(fact, ...)
x %==% y

Arguments

fact

a message for the assertions when any of them fails; treated the same way as expressions in ... if it is not a character string, which means you do not have to provide a message to this function

...

an R expression; see Details

x, y

two R objects to be compared

Value

For assert(), invisible NULL if all expressions returned TRUE, otherwise an error is signalled and the user-provided message is emitted. For %==%, TRUE or FALSE.

Details

For the ... argument, it should be a single R expression wrapped in {}. This expression may contain multiple sub-expressions. A sub-expression is treated as a test condition if it is wrapped in () (meaning its value will be checked to see if it is a logical vector containing any FALSE values) , otherwise it is evaluated in the normal way and its value will not be checked. If the value of the last sub-expression is logical, it will also be treated as a test condition.

Examples

# NOT RUN {
## The first way to write assertions -------------------

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)  # () is optional because it's the last expression
})


## The second way to write assertions --------------------

assert("one equals one", 1 == 1)
assert("seq and : produce equal sequences", seq(1L, 10L) == 1L:10L)
assert("seq and : produce identical sequences", identical(seq(1L, 10L), 1L:10L))

# multiple tests
T = FALSE
F = TRUE
assert("T is bad for TRUE, and so is F for FALSE", T != TRUE, F != FALSE)

# a mixture of tests
assert("Let's pray all of them will pass", 1 == 1, 1 != 2, letters[4] == "d", 
    rev(rev(letters)) == letters)

# logical(0) cannot pass assert(), although stopifnot() does not care
try(assert("logical(0) cannot pass", 1 == integer(0)))
stopifnot(1 == integer(0))  # it's OK!

# a compound expression
try(assert("this if statement returns TRUE", if (TRUE) {
    x = 1
    x == 2
}))

# no message
assert(!FALSE, TRUE, is.na(NA))
# }