Use test_dir() for a collection of tests in a directory; use test_package() interactively at the console, and test_check() inside of R CMD check.

In your own code, you can use is_testing() to determine if code is being run as part of a test and testing_package() to retrieve the name of the package being tested. You can also check the underlying env var directly identical(Sys.getenv("TESTTHAT"), "true") to avoid creating a run-time dependency on testthat.

test_dir(path, filter = NULL, reporter = default_reporter(),
  env = test_env(), ..., encoding = "unknown", load_helpers = TRUE,
  stop_on_failure = FALSE, stop_on_warning = FALSE, wrap = TRUE)

test_package(package, filter = NULL, reporter = check_reporter(), ...,
  stop_on_failure = TRUE, stop_on_warning = FALSE)

test_check(package, filter = NULL, reporter = check_reporter(), ...,
  stop_on_failure = TRUE, stop_on_warning = FALSE, wrap = TRUE)

is_testing()

testing_package()

Arguments

path

Path to directory containing tests.

filter

If not NULL, only tests with file names matching this regular expression will be executed. Matching be performed on the file name after it has been 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.

encoding

Deprecated. All files now assumed to be UTF-8.

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.

For historical reasons, the default value of stop_on_failure is TRUE for test_package() and test_check() but FALSE for test_dir(), so if you're calling test_dir() you may want to consider explicitly setting stop_on_failure = TRUE.

stop_on_warning

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

wrap

Automatically wrap all code within test_that()? This ensures that all expectations are reported, even if outside a test block.

package

Name of installed package.

Value

A list of test results.

Test files

For package code, tests should live in tests/testthat.

There are four classes of .R files that have special behaviour:

  • Test files start with test and are executed in alphabetical order.

  • Helper files start with helper and are executed before tests are run and from devtools::load_all().

  • Setup files start with setup and are executed before tests, but not during devtools::load_all().

  • Teardown files start with teardown and are executed after the tests are run.

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.

R CMD check

To run testthat automatically from R CMD check, make sure you have a tests/testthat.R that contains:

library(testthat)
library(yourpackage)

test_check("yourpackage")

Examples

test_dir(testthat_examples(), reporter = "summary")
#> .1.SW... #> ══ Skipped ═════════════════════════════════════════════════════════════════════ #> 1. you can skip tests if needed (@test-success.R#6) - Reason: This tests hasn't been written yet #> #> ══ Warnings ════════════════════════════════════════════════════════════════════ #> 1. some tests have warnings (@test-success.R#10) - NaNs produced #> #> ══ Failed ══════════════════════════════════════════════════════════════════════ #> ── 1. Failure: two plus two is four (@test-failure.R#8) ─────────────────────── #> plus(2, 2) not equal to 4. #> 1/1 mismatches #> [1] 2 - 4 == -2 #> #> ══ DONE ════════════════════════════════════════════════════════════════════════
test_dir(testthat_examples(), reporter = "minimal")
#> .F.SW...