test_pkg {testit}R Documentation

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.

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/#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)
[Package testit version 1.0 Index]