test_pkg: Run all tests for a package

In testit: A Simple Package for Testing R Packages

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) in the test directory are sourced before any test file runs. Objects defined in helpers are available to all tests. To share helpers across multiple test subdirectories, put them in a sibling ⁠helpers/⁠ directory (e.g., ⁠tests/helpers/⁠); all .R files there are sourced first, before the test subdirectory's own helpers.

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

## Not run: 
library(testit)
test_pkg('testit')

## End(Not run)

testit documentation built on Oct. 16, 2026, 1:06 a.m.