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

382,417

Version

2.0.0

License

MIT + file LICENSE

Issues

125

Pull Requests

27

Stars

903

Forks

330

Maintainer

Hadley Wickham

Last Published

December 13th, 2017

Functions in testthat (2.0.0)

MinimalReporter

Test reporter: minimal.
DebugReporter

Test reporter: start recovery.
ProgressReporter

Test reporter: interactive progress bar of errors.
Reporter

Stub object for managing a reporter of tests.
StopReporter

Test reporter: stop on error.
evaluate_promise

Evaluate a promise, capturing all types of output.
SummaryReporter

Test reporter: summary of errors.
expect

The building block of all expect_ functions
expect_cpp_tests_pass

Test Compiled Code in a Package
RstudioReporter

Test reporter: RStudio
expect_known_output

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

Test reporter: gather all errors silently.
FailReporter

Test reporter: fail at end.
dir_state

Capture the state of a directory.
JunitReporter

Test reporter: summary of errors in jUnit XML format.
equality-expectations

Expectation: is the object equal to a value?
compare

Provide human-readable comparison of two objects
compare_state

Compare two directory states.
auto_test

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

Expectation: does a vector have the specified length?
auto_test_package

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

Expectation: does string match a regular expression?
logical-expectations

Expectation: is the object true/false?
comparison-expectations

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

Make an equality test.
context

Describe the context of a set of tests.
not

Negate an expectation
oldskool

Old-style expectations.
expect_that

Expect that a condition holds.
safe_digest

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

Construct an expectation object
skip

Skip a test.
test_that

Create a test.
MultiReporter

Multi reporter: combine several reporters in one.
testthat-package

R package to make testing fun!
TapReporter

Test reporter: TAP format.
expect_success

Tools for testing expectations
TeamcityReporter

Test reporter: Teamcity format.
output-expectations

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

Quasi-labelling
expect_named

Expectation: does object have names?
source_file

Source a file, directory, or all helpers.
testthat_results

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

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

Try evaluating an expressing multiple times until it succeeds.
reexports

Objects exported from other packages
reporter-accessors

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

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

Run all tests in specified file.
LocationReporter

Test reporter: location
test_path

Locate file in testing directory.
capture_condition

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

Use Catch for C++ Unit Testing
watch

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

Capture output to console
fail

Default expectations that alway succeed or fail.
default_reporter

Retrieve the default reporter.
find_reporter

Find reporter object given name or object.
test_env

Generate default testing environment.
find_test_scripts

Find the test files.
inheritance-expectations

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

Test package examples
describe

describe: a BDD testing language
with_mock

Mock functions in a package.
teardown

Run code on setup/teardown
test_dir

Run all tests in directory or package
CheckReporter

Check reporter: 13 line summary of problems