test_dir: Run all tests in a directory

Description

This function is the low-level workhorse that powers test_local() and test_package(). Generally, you should not call this function directly. In particular, you are responsible for ensuring that the functions to test are available in the test env (e.g. via load_package).

Usage

test_dir(
  path,
  filter = NULL,
  reporter = NULL,
  env = NULL,
  ...,
  load_helpers = TRUE,
  stop_on_failure = TRUE,
  stop_on_warning = FALSE,
  wrap = lifecycle::deprecated(),
  package = NULL,
  load_package = c("none", "installed", "source")
)

Value

A list (invisibly) containing data about the test results.

Arguments

path

Path to directory containing tests.

filter

If not NULL, only tests with file names matching this regular expression will be executed. Matching is performed on the file name after it's stripped of "test-" and ".R".

reporter

Reporter to use to summarise output. Can be supplied as a string (e.g. "summary") or as an R6 object (e.g. SummaryReporter$new()).

See Reporter for more details and a list of built-in reporters.

env

Environment in which to execute the tests. Expert use only.

...

Additional arguments passed to grepl() to control filtering.

load_helpers

Source helper files before running the tests? See source_test_helpers() for more details.

stop_on_failure

If TRUE, throw an error if any tests fail.

stop_on_warning

If TRUE, throw an error if any tests generate warnings.

wrap

DEPRECATED

package

If these tests belong to a package, the name of the package.

load_package

Strategy to use for load package code:

"none", the default, doesn't load the package.
"installed", uses library() to load an installed package.
"source", uses pkgload::load_all() to a source package. To configure the arguments passed to load_all(), add this field in your DESCRIPTION file:
```
Config/testthat/load-all: list(export_all = FALSE, helpers = FALSE)
```

Special files

Certain .R files have special significance in testthat:

Test files start with test and are executed in alphabetical order.
Setup files start with setup and are executed before tests. If clean up is needed after all tests have been run, you can use withr::defer(clean_up(), teardown_env()). See vignette("test-fixtures") for more details.
Helper files start with helper and are executed before tests are run and, unlike setup files, are also loaded by devtools::load_all(). Helper files can be necessary for side-effect-y code that you need to run when developing the package interactively. It's certainly possible to define custom test utilities in a helper file, but they can usually be defined below R/, just like any other internal function.

There is another type of special file that we no longer recommend using:

Teardown files start with teardown and are executed after the tests are run. Now we recommend interleaving setup and cleanup code in setup- files, making it easier to check that you automatically clean up every mess that you make.

All other files are ignored by testthat.

Environments

Each test is run in a clean environment to keep tests as isolated as possible. For package tests, that environment that inherits from the package's namespace environment, so that tests can access internal functions and objects.