testthat v2.3.2


Monthly downloads



Unit Testing for R

Software testing is important, but, in part because it is frustrating and boring, many of us avoid it. 'testthat' is a testing framework for R that is easy to learn and use, and integrates with your existing 'workflow'.



status Travis build
status R build
status Codecov test


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.


# Install the released version from CRAN

# Or the development version from GitHub:
# install.packages("devtools")


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.

Functions in testthat

Name Description
CheckReporter Check reporter: 13 line summary of problems
DebugReporter Test reporter: start recovery.
Reporter Manage test reporting
ProgressReporter Test reporter: interactive progress bar of errors.
capture_condition Capture conditions, including messeages, warnings, expectations, and errors.
capture_output Capture output to console
StopReporter Test reporter: stop on error.
SummaryReporter Test reporter: summary of errors.
TapReporter Test reporter: TAP format.
SilentReporter Test reporter: gather all errors silently.
RstudioReporter Test reporter: RStudio
equality-expectations Expectation: is the object equal to a value?
dir_state Capture the state of a directory.
auto_test Watches code and tests for changes, rerunning tests as appropriate.
context Describe the context of a set of tests.
describe describe: a BDD testing language
default_reporter Retrieve the default reporter
expect_match Expectation: does string match a regular expression?
expect_null Expectation: is an object NULL?
expect_output Expectation: does code print output to the console?
quasi_label Quasi-labelling
auto_test_package Watches a package for changes, rerunning tests as appropriate.
expect_less_than Deprecated numeric comparison functions
skip Skip a test.
fail Default expectations that always succeed or fail.
TeamcityReporter Test reporter: Teamcity format.
expect_length Expectation: does a vector have the specified length?
oldskool Old-style expectations.
expect_message Expectation: does code produce warnings or messages?
expect_named Expectation: does object have names?
find_reporter Find reporter object given name or object.
compare Provide human-readable comparison of two objects
expect_vector Expectation: does the object have vctr properties?
inheritance-expectations Expectation: does the object inherit from a S3 or S4 class, or is it a base type?
expect The building block of all expect_ functions
compare_state Compare two directory states.
expect_known_output Expectations: is the output or the value equal to a known good value?
comparison-expectations Expectation: is returned value less or greater than specified value?
make_expectation Make an equality test.
expect_error Expectation: does code throw error or other condition?
expect_silent Expectation: is the code silent?
evaluate_promise Evaluate a promise, capturing all types of output.
expect_setequal Expectation: do two vectors contain the same values?
find_test_scripts Find the test files.
not Negate an expectation
expect_cpp_tests_pass Expectation: do C++ tests past?
teardown Run code on setup/teardown
test_dir Run all tests in directory or package
reexports Objects exported from other packages
test_that Create a test.
use_catch Use Catch for C++ Unit Testing
try_again Try evaluating an expressing multiple times until it succeeds.
logical-expectations Expectation: is the object true/false?
safe_digest Compute a digest of a filename, returning NA if the file doesn't exist.
expectation Construct an expectation object
expect_invisible Expectation: does expression return visibily or invisibly?
testthat-package R package to make testing fun!
is_informative_error Is an error informative?
test_file Run all tests in specified file
expect_success Tools for testing expectations
expect_that Expect that a condition holds.
takes_less_than Expectation: does expression take less than a fixed amount of time to run?
reporter-accessors Get and set active reporter.
expect_is Expectation: does the object inherit from a given class?
source_file Source a file, directory of files, or various important subsets
test_path Locate file in testing directory.
with_mock Mock functions in a package.
test_env Generate default testing environment.
verify_output Verify output
testthat_examples Retrieve paths to built-in example test files
watch Watch a directory for changes (additions, deletions & modifications).
test_examples Test package examples
testthat_results Create a testthat_results object from the test results as stored in the ListReporter results field.
MinimalReporter Test reporter: minimal.
MultiReporter Multi reporter: combine several reporters in one.
FailReporter Test reporter: fail at end.
LocationReporter Test reporter: location
JunitReporter Test reporter: summary of errors in jUnit XML format.
ListReporter List reporter: gather all test results along with elapsed time and file information.
No Results!

Vignettes of testthat

No Results!

Last month downloads


License MIT + file LICENSE
URL http://testthat.r-lib.org, https://github.com/r-lib/testthat
BugReports https://github.com/r-lib/testthat/issues
VignetteBuilder knitr
Encoding UTF-8
RoxygenNote 7.0.2
Collate 'auto-test.R' 'capture-condition.R' 'capture-output.R' 'colour-text.R' 'compare.R' 'compare-character.R' 'compare-numeric.R' 'compare-time.R' 'context.R' 'describe.R' 'evaluate-promise.R' 'example.R' 'expect-comparison.R' 'expect-condition.R' 'expect-equality.R' 'expect-inheritance.R' 'expect-invisible.R' 'expect-known.R' 'expect-length.R' 'expect-logical.R' 'expect-messages.R' 'expect-named.R' 'expect-null.R' 'expect-output.R' 'reporter.R' 'expect-self-test.R' 'expect-setequal.R' 'expect-silent.R' 'expect-that.R' 'expect-vector.R' 'expectation.R' 'expectations-matches.R' 'make-expectation.R' 'mock.R' 'old-school.R' 'praise.R' 'quasi-label.R' 'recover.R' 'reporter-check.R' 'reporter-debug.R' 'reporter-fail.R' 'reporter-junit.R' 'reporter-list.R' 'reporter-location.R' 'reporter-minimal.R' 'reporter-multi.R' 'stack.R' 'reporter-progress.R' 'reporter-rstudio.R' 'reporter-silent.R' 'reporter-stop.R' 'reporter-summary.R' 'reporter-tap.R' 'reporter-teamcity.R' 'reporter-zzz.R' 'skip.R' 'source.R' 'teardown.R' 'test-compiled-code.R' 'test-directory.R' 'test-example.R' 'test-files.R' 'test-path.R' 'test-that.R' 'try-again.R' 'utils-io.R' 'utils.R' 'verify-output.R' 'watcher.R'
NeedsCompilation yes
Packaged 2020-03-02 14:59:34 UTC; hadley
Repository CRAN
Date/Publication 2020-03-02 15:40:02 UTC

Include our badge in your README