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 to run all the tests in a package.

Copy Link

Version

Install

install.packages('testthat')

Monthly Downloads

578,511

Version

2.0.1

License

MIT + file LICENSE

Issues

118

Pull Requests

25

Stars

902

Forks

327

Maintainer

Hadley Wickham

Last Published

October 13th, 2018

Functions in testthat (2.0.1)

ProgressReporter

Test reporter: interactive progress bar of errors.
expect_known_output

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

Negate an expectation
oldskool

Old-style expectations.
testthat_results

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

Try evaluating an expressing multiple times until it succeeds.
FailReporter

Test reporter: fail at end.
JunitReporter

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

Test reporter: TAP format.
TeamcityReporter

Test reporter: Teamcity format.
StopReporter

Test reporter: stop on error.
compare

Provide human-readable comparison of two objects
SummaryReporter

Test reporter: summary of errors.
default_reporter

Retrieve the default reporter.
compare_state

Compare two directory states.
describe

describe: a BDD testing language
expect_that

Expect that a condition holds.
expectation

Construct an expectation object
expect_named

Expectation: does object have names?
expect_success

Tools for testing expectations
find_test_scripts

Find the test files.
inheritance-expectations

Expectation: does the object inherit from a S3 or S4 class, or a base type?
source_file

Source a file, directory, or all helpers.
teardown

Run code on setup/teardown
test_dir

Run all tests in directory or package
takes_less_than

Expectation: does expression take less than a fixed amount of time to run?
use_catch

Use Catch for C++ Unit Testing
watch

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

Test reporter: minimal.
ListReporter

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

Test reporter: location
MultiReporter

Multi reporter: combine several reporters in one.
auto_test

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

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

Capture output to console
comparison-expectations

Expectation: is returned value less or greater than specified value?
auto_test_package

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

Describe the context of a set of tests.
evaluate_promise

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

Expectation: does code produce output/message/warning/error?
expect

The building block of all expect_ functions
quasi_label

Quasi-labelling
test_env

Generate default testing environment.
fail

Default expectations that alway succeed or fail.
test_examples

Test package examples
CheckReporter

Check reporter: 13 line summary of problems
DebugReporter

Test reporter: start recovery.
RstudioReporter

Test reporter: RStudio
find_reporter

Find reporter object given name or object.
SilentReporter

Test reporter: gather all errors silently.
equality-expectations

Expectation: is the object equal to a value?
dir_state

Capture the state of a directory.
logical-expectations

Expectation: is the object true/false?
expect_length

Expectation: does a vector have the specified length?
make_expectation

Make an equality test.
expect_match

Expectation: does string match a regular expression?
test_file

Run all tests in specified file.
test_path

Locate file in testing directory.
reexports

Objects exported from other packages
reporter-accessors

Get/set reporter; execute code in specified reporter.
safe_digest

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

Skip a test.
test_that

Create a test.
testthat-package

R package to make testing fun!
with_mock

Mock functions in a package.
expect_cpp_tests_pass

Test Compiled Code in a Package
Reporter

Stub object for managing a reporter of tests.