testthat v2.0.0


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 learn and use, and integrates with your existing 'workflow'.



Travis-CI Build Status AppVeyor Build Status Coverage status CRAN version


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

Functions in testthat

Name Description
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
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.0.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' 'expect-comparison.R' 'expect-equality.R' 'expect-inheritance.R' 'expect-known.R' 'expect-length.R' 'expect-logical.R' 'expect-named.R' 'expect-output.R' 'reporter.R' 'expect-self-test.R' 'expect-that.R' 'expectation.R' 'expectations-matches.R' 'make-expectation.R' 'mock.R' 'old-school.R' 'praise.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' 'watcher.R'
NeedsCompilation yes
Packaged 2017-11-28 16:44:21 UTC; hadley
Repository CRAN
Date/Publication 2017-12-13 09:30:12 UTC

Include our badge in your README