testthat v2.2.1


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

Include our badge in your README