Learn R Programming

⚠️There's a newer version (3.2.3) of this package.Take me there.

testthat

Overview

Testing your code can be painful and tedious, but it greatly increases the quality of your code. testthat tries to make testing as fun as possible, so that you get a visceral satisfaction from writing tests. Testing should be addictive, so you do it all the time. To make that happen, testthat:

  • Provides functions that make it easy to describe what you expect a function to do, including catching errors, warnings, and messages.

  • Easily integrates in your existing workflow, whether it’s informal testing on the command line, building test suites, or using R CMD check.

  • Displays test progress visually, showing a pass, fail, or error for every expectation. If you’re using the terminal or a recent version of RStudio, it’ll even colour the output.

testthat draws inspiration from the xUnit family of testing packages, as well as from many of the innovative ruby testing libraries, like rspec, testy, bacon and cucumber.

testthat is the most popular unit testing package for R and is used by thousands of CRAN packages.

If you’re not familiar with testthat, the testing chapter in R packages gives a good overview, along with workflow advice and concrete examples.

Installation

# Install the released version from CRAN
install.packages("testthat")

# Or the development version from GitHub:
# install.packages("devtools")
devtools::install_github("r-lib/testthat")

Usage

The easiest way to get started is with usethis. Assuming you’re in a package directory, just run usethis::use_test("name") to create a test file, and set up all the other infrastructure you need. If you’re using RStudio, press Cmd/Ctrl + Shift + T (or run devtools::test() if not) to run all the tests in a package.

Copy Link

Version

Install

install.packages('testthat')

Monthly Downloads

382,417

Version

3.1.1

License

MIT + file LICENSE

Issues

Pull Requests

Stars

Forks

Maintainer

Hadley Wickham

Last Published

December 3rd, 2021

Functions in testthat (3.1.1)

FailReporter

Test reporter: fail at end.
LocationReporter

Test reporter: location
ProgressReporter

Test reporter: interactive progress bar of errors.
DebugReporter

Test reporter: start recovery.
MultiReporter

Multi reporter: combine several reporters in one.
JunitReporter

Test reporter: summary of errors in jUnit XML format.
StopReporter

Test reporter: stop on error
SummaryReporter

Test reporter: summary of errors.
Reporter

Manage test reporting
RStudioReporter

Test reporter: RStudio
SilentReporter

Test reporter: gather all errors silently.
expect_that

Expect that a condition holds.
expect_named

Does code return a vector with (given) names?
expect_match

Does a string match a regular expression?
expect_success

Tools for testing expectations
equality-expectations

Does code return the expected value?
expect_error

Does code throw an error, warning, message, or other condition?
expect_invisible

Does code return a visible or invisible object?
capture_condition

Capture conditions, including messages, warnings, expectations, and errors.
capture_output

Capture output to console
evaluate_promise

Evaluate a promise, capturing all types of output.
comparison-expectations

Does code return a number greater/less than the expected value?
expect_setequal

Does code return a vector containing the expected values?
expect_silent

Does code execute silently?
TapReporter

Test reporter: TAP format.
expect_vector

Does code return a vector with the expected size and/or prototype?
TeamcityReporter

Test reporter: Teamcity format.
context_start_file

Start test context from a file name
expect

The building block of all expect_ functions
compare

Provide human-readable comparison of two objects
expect_output_file

Expectations: is the output or the value equal to a known good value?
compare_state

Compare two directory states.
auto_test

Watches code and tests for changes, rerunning tests as appropriate.
auto_test_package

Watches a package for changes, rerunning tests as appropriate.
default_reporter

Retrieve the default reporter
describe

describe: a BDD testing language
expect_length

Does code return a vector with the specified length?
context

Describe the context of a set of tests.
expect_equivalent

Is an object equal to the expected value, ignoring attributes?
expect_reference

Does code return a reference to the expected object?
expect_less_than

Deprecated numeric comparison functions
fail

Default expectations that always succeed or fail.
reexports

Objects exported from other packages
find_reporter

Find reporter object given name or object.
quasi_label

Quasi-labelling
expect_null

Does code return NULL?
expect_output

Does code print output to the console?
inheritance-expectations

Does code return an object inheriting from the expected base type, S3 class, or S4 class?
make_expectation

Make an equality test.
logical-expectations

Does code return TRUE or FALSE?
expect_snapshot_file

Snapshot testing for whole files
expect_snapshot

Snapshot testing
find_test_scripts

Find test files
local_edition

Temporarily change the active testthat edition
local_snapshotter

Instantiate local snapshotting context
snapshot_accept

Snapshot management
source_file

Source a file, directory of files, or various important subsets
dir_state

Capture the state of a directory.
test_package

Run all tests in a package
test_file

Run all tests in a single file
test_path

Locate file in testing directory.
test_that

Run a test
teardown_env

Run code after all test files
test_dir

Run all tests in a directory
expect_known_output

Expectations: is the output or the value equal to a known good value?
local_test_context

Locally set options for maximal test reproducibility
expect_is

Does an object inherit from a given class?
local_test_directory

Locally set test directory options
takes_less_than

Does code take less than the expected amount of time to run?
testthat-package

An R package to make testing fun!
testthat_results

Create a testthat_results object from the test results as stored in the ListReporter results field.
expectation

Construct an expectation object
is_testing

Determine testing status
is_informative_error

Is an error informative?
teardown

Run code before/after tests
try_again

Try evaluating an expressing multiple times until it succeeds.
testthat_examples

Retrieve paths to built-in example test files
reporter-accessors

Get and set active reporter.
expect_cpp_tests_pass

Do C++ tests past?
test_env

Generate default testing environment.
not

Negate an expectation
with_mock

Mock functions in a package.
watch

Watch a directory for changes (additions, deletions & modifications).
use_catch

Use Catch for C++ Unit Testing
test_examples

Test package examples
verify_output

Verify output
skip

Skip a test
oldskool

Old-style expectations.
safe_digest

Compute a digest of a filename, returning NA if the file doesn't exist.
MinimalReporter

Test reporter: minimal.
CheckReporter

Check reporter: 13 line summary of problems
ListReporter

List reporter: gather all test results along with elapsed time and file information.