Help pages

1 Assert that conditions are true, with an informative failure message
2 Test whether an expression signals a condition
3 Run all tests for a package

-- A -- assert()

-- H -- has_message() has_warning() has_error()

-- T -- test_pkg()

-- misc -- %==%()

1 Assert that conditions are true, with an informative failure message

Description

Test that one or more conditions are TRUE. If any condition fails, an error is raised with the fact message, making it easy to identify which test failed and why. This is the primary function for writing tests with testit.

The infix operator %==% is a shortcut for identical() that provides helpful diagnostics on failure. x %==% y returns TRUE if x and y are identical, and FALSE otherwise. When used inside assert(), a failing %==% comparison will display both values via str() so you can see exactly what differed.

Usage

assert(fact, ...)

x %==% y

Arguments

fact

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

...

An R expression wrapped in {}; see Details.

x, y

Two R objects to be compared for identity.

Details

The recommended usage is to pass a single expression wrapped in {} as the second argument. Inside {}, any statement-level sub-expression wrapped in parentheses () is treated as a test condition – its value is checked and must be TRUE. Parentheses used for grouping within a larger expression (e.g., (a + b) * c) are not checked. Sub-expressions without parentheses are ordinary R code (e.g., variable assignments or setup steps) and are never checked.

() tests work inside if, for, while, and repeat bodies. Internally, assert() walks the expression tree and transforms statement-level () into checks before evaluating the entire block in one frame (so on.exit() works as expected).

Value

Invisible NULL if all conditions pass. If any condition fails, an error is signaled that includes the fact message and the expression that failed. For %==%, TRUE or FALSE.

Note

Key differences from stopifnot():

assert() shows your custom fact message on failure, making errors easier to diagnose.
logical(0) (empty logical) is treated as a failure, not a pass.
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)
})

2 Test whether an expression signals a condition

Description

Check if evaluating an expression produces a message, warning, or error. These functions are designed to be used inside assert() to verify that code signals the expected conditions. Optionally, you can match against the condition's text to ensure the right message/warning/error was signaled.

Usage

has_message(expr, message = NULL, ...)

has_warning(expr, message = NULL, ...)

has_error(expr, message = NULL, ...)

Arguments

expr

An R expression to evaluate.

message

An optional string to match against the condition text. Uses fixed (literal) matching by default. If provided, the function returns TRUE only when the condition is signaled and the message matches.

...

Additional arguments passed to grepl() for matching (e.g., fixed = FALSE to use regex, or ignore.case = TRUE). Note that fixed = TRUE is the default.

Value

TRUE if the condition was signaled (and the message matched, if provided), FALSE otherwise.

Examples

has_message(message('hello'))

#> [1] TRUE

has_message(1 + 1)

#> [1] FALSE

has_message(message('hello world'), 'hello')

#> [1] TRUE

has_warning(1 + 1)

#> [1] FALSE

has_warning(1:2 + 1:3)

#> [1] TRUE

has_warning(1:2 + 1:3, 'longer object length')

#> [1] TRUE

has_error(2 - 3)

#> [1] FALSE

has_error(1 + 'a')

#> [1] TRUE

has_error(stop('err'), 'err')

#> [1] TRUE

has_error(stop('error occurred'), 'error')

#> [1] TRUE

3 Run all tests for a package

Description

Discover and execute test files (test-*.R and test-*.md) for a package. Tests are run inside the package namespace, so you can call internal (non-exported) functions directly without the ::: operator.

Usage

test_pkg(package = pkg_name(), dir = NULL, filter = NULL, update = NA)

Arguments

package

The package name. By default, it is detected from the DESCRIPTION file.

dir

The directory containing test files. If NULL (the default), testit/ or tests/testit/ under the current working directory is used (whichever exists). You can also pass a custom path.

filter

An optional regular expression to select a subset of test files. Only files whose names match the pattern will be run. For example, filter = "plot" runs only test files with "plot" in their names.

update

Controls snapshot file behavior:

TRUE: always update snapshot files with actual output (never errors).
NA (default): update only if the file is tracked by Git (so you can review diffs before accepting).
FALSE: never update; always compare and error on mismatch.

Details

Test files are looked up in the testit/ or tests/testit/ directory by default. Files must be named test-*.R for regular tests or test-*.md for snapshot tests. Other files in the directory are ignored (but you can source() them from your tests if needed).

Helper files named helper*.R (e.g., helper.R, helper-utils.R) are sourced before any test file runs. Objects defined in helpers are available to all tests. Global helpers in the parent directory (e.g., tests/helper.R) are sourced first, followed by helpers in the test subdirectory itself. This allows you to share common utilities across all test subdirectories.

Each test file runs in a clean environment (previous test objects are removed), and the working directory is set to the directory containing the test file.

See https://pkg.yihui.org/testit/#sec:snapshot-testing for more details about snapshot testing.

Value

Invisible NULL. If any tests fail, a single error is thrown at the end with all failure messages combined.

Note

You must call library(testit) before test_pkg(). Test scripts use assert() and other testit functions without the testit:: prefix, so the package needs to be on the search path. Without library(testit), you will get "could not find function" errors.

All test scripts must be encoded in UTF-8 if they contain multibyte characters.

When filter or update are not explicitly provided, test_pkg() checks commandArgs(TRUE) for command-line arguments: --filter=PATTERN sets the filter, and --update sets update = TRUE. This allows you to pass these options via Rscript tests/*.R --filter=PATTERN --update without modifying individual test_pkg() calls.

Examples

library(testit)
test_pkg('testit')