Learn R Programming

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("pak")
pak::pak("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 (or run devtools::test() if not) to run all the tests in a package.

Copy Link

Version

Install

install.packages('testthat')

Monthly Downloads

1,311,799

Version

3.3.1

License

MIT + file LICENSE

Issues

7

Pull Requests

4

Stars

919

Forks

341

Maintainer

Hadley Wickham

Last Published

November 25th, 2025

Functions in testthat (3.3.1)

RStudioReporter

Report results to RStudio
expect_named

Do you expect a vector with (these) names?
expect_all_equal

Do you expect every value in a vector to have this value?
comparison-expectations

Do you expect a value bigger or smaller than this?
expect_no_error

Do you expect the absence of errors, warnings, messages, or other conditions?
context

Describe the context of a set of tests.
expect_invisible

Do you expect the result to be (in)visible?
expect_snapshot_value

Do you expect this code to return the same value as last time?
expect

The previous building block of all expect_ functions
expect_is

Do you expect to inherit from this class?
capture_condition

Capture conditions, including messages, warnings, expectations, and errors.
expect_match

Do you expect a string to match this pattern?
expect_less_than

Deprecated numeric comparison functions
expect_success

Test your custom expectations
inheritance-expectations

Do you expect an S3/S4/R6/S7 object that inherits from this class?
context_start_file

Start test context from a file name
find_test_scripts

Find test files
StopReporter

Error if any test fails
SlowReporter

Find slow tests
default_reporter

Retrieve the default reporter
capture_output

Capture output to console
expect_length

Do you expect an object with this length or shape?
is_testing

Determine testing status
expect_known_output

Do you expect the results/output to equal a known value?
expect_cpp_tests_pass

Do C++ tests past?
quasi_label

Quasi-labelling
is_informative_error

Is an error informative?
reporter-accessors

Get and set active reporter.
expect_snapshot_file

Do you expect this code to create the same file as last time?
expect_output

Do you expect printed output to match this pattern?
expect_output_file

Do you expect the output/result to equal a known good value?
set_state_inspector

Check for global state changes
mock_output_sequence

Mock a sequence of output from a function
set_max_fails

Set maximum number of test failures allowed before aborting the run
expect_snapshot_output

Snapshot helpers
takes_less_than

Does code take less than the expected amount of time to run?
make_expectation

Make an equality test.
teardown

Run code before/after tests
expect_null

Do you expect NULL?
expect_no_success

Test for absence of success or failure
source_file

Source a file, directory of files, or various important subsets
test_that

Run a test
test_path

Locate a file in the testing directory
testthat_results

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

Mark a test as successful
reexports

Objects exported from other packages
test_dir

Run all tests in a directory
teardown_env

Run code after all test files
testthat_tolerance

Default numeric tolerance
with_mock

Mock functions in a package.
watch

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

Capture the state of a directory.
describe

describe: a BDD testing language
expect_error

Do you expect an error, warning, message, or other condition?
expect_equivalent

Is an object equal to the expected value, ignoring attributes?
expect_that

Expect that a condition holds.
use_catch

Use Catch for C++ unit testing
verify_output

Verify output
expect_snapshot

Do you expect this code to run the same way as last time?
expect_silent

Do you expect code to execute silently?
fail

Declare that an expectation either passes or fails
expect_vector

Do you expect a vector with this size and/or prototype?
local_mocked_bindings

Temporarily redefine function definitions
local_edition

Temporarily change the active testthat edition
oldskool

Old-style expectations.
local_mocked_r6_class

Mock an R6 class
find_reporter

Find reporter object given name or object.
not

Negate an expectation
local_mocked_s3_method

Mock S3 and S4 methods
skip

Skip a test for various reasons
expect_setequal

Do you expect a vector containing these values?
extract_test

Extract a reprex from a failed expectation
expect_reference

Do you expect a reference to this object?
local_snapshotter

Instantiate local snapshotting context
expectation

Expectation conditions
local_test_context

Temporarily set options for maximum reproducibility
testthat-package

An R package to make testing fun!
logical-expectations

Do you expect TRUE or FALSE?
local_test_directory

Locally set test directory options
testthat_examples

Retrieve paths to built-in example test files
snapshot_download_gh

Download snapshots from GitHub
test_file

Run tests in a single file
snapshot_accept

Accept or reject modified snapshots
skip_on_travis

Superseded skip functions
test_package

Run all tests in a package
test_examples

Test package examples
try_again

Evaluate an expectation multiple times until it succeeds
test_env

Generate default testing environment.
simulate_test_env

Simulate a test environment
FailReporter

Fail if any tests fail
LocationReporter

Test reporter: location
DebugReporter

Interactively debug failing tests
MinimalReporter

Report minimal results as compactly as possible
ProgressReporter

Report progress interactively
CheckReporter

Report results for R CMD check
MultiReporter

Run multiple reporters at the same time
JunitReporter

Report results in jUnit XML format
ListReporter

Capture test results and metadata
SummaryReporter

Report a summary of failures
auto_test

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

Report results in Teamcity format
SilentReporter

Silently collect and all expectations
Reporter

Manage test reporting
compare

Provide human-readable comparison of two objects
equality-expectations

Do you expect this value?
evaluate_promise

Evaluate a promise, capturing all types of output.
compare_state

Compare two directory states.
TapReporter

Report results in TAP format