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.0

License

MIT + file LICENSE

Issues

Pull Requests

Stars

Forks

Repository

https://github.com/r-lib/testthat

Homepage

https://testthat.r-lib.org

Maintainer

Hadley Wickham

Last Published

November 13th, 2025

Functions in testthat (3.3.0)

describe: a BDD testing language

Report results in TAP format

Find slow tests

context_start_file

Start test context from a file name

default_reporter

Retrieve the default reporter

equality-expectations

Do you expect this value?

evaluate_promise

Evaluate a promise, capturing all types of output.

expect_all_equal

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

The previous building block of all expect_ functions

Provide human-readable comparison of two objects

Error if any test fails

Do you expect an object with this length or shape?

Compare two directory states.

expect_known_output

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

expect_equivalent

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

Do you expect code to execute silently?

expect_snapshot

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

Capture the state of a directory.

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

expect_no_error

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

Do you expect a vector with (these) names?

expect_less_than

Deprecated numeric comparison functions

expect_setequal

Do you expect a vector containing these values?

Do you expect a string to match this pattern?

expect_reference

Do you expect a reference to this object?

expect_snapshot_output

Snapshot helpers

expect_snapshot_file

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

Expect that a condition holds.

expect_no_success

Test for absence of success or failure

Do you expect NULL?

local_snapshotter

Instantiate local snapshotting context

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

Do you expect printed output to match this pattern?

Extract a reprex from a failed expectation

Temporarily change the active testthat edition

Expectation conditions

expect_output_file

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

local_mocked_s3_method

Mock S3 and S4 methods

local_mocked_r6_class

Mock an R6 class

Test your custom expectations

expect_snapshot_value

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

local_test_context

Temporarily set options for maximum reproducibility

Quasi-labelling

Objects exported from other packages

reporter-accessors

Get and set active reporter.

expect_cpp_tests_pass

Do C++ tests past?

mock_output_sequence

Mock a sequence of output from a function

make_expectation

Make an equality test.

takes_less_than

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

inheritance-expectations

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

find_test_scripts

Find test files

set_state_inspector

Check for global state changes

Set maximum number of test failures allowed before aborting the run

local_mocked_bindings

Temporarily redefine function definitions

Old-style expectations.

testthat-package

An R package to make testing fun!

Negate an expectation

Mark a test as successful

testthat_examples

Retrieve paths to built-in example test files

Run code after all test files

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

Generate default testing environment.

Run all tests in a directory

Test package examples

snapshot_accept

Accept or reject modified snapshots

logical-expectations

Do you expect TRUE or FALSE?

local_test_directory

Locally set test directory options

Run tests in a single file

Run code before/after tests

Mock functions in a package.

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

snapshot_download_gh

Download snapshots from GitHub

Evaluate an expectation multiple times until it succeeds

simulate_test_env

Simulate a test environment

Declare that an expectation either passes or fails

Use Catch for C++ unit testing

Run all tests in a package

comparison-expectations

Do you expect a value bigger or smaller than this?

expect_invisible

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

Describe the context of a set of tests.

Do you expect to inherit from this class?

Determine testing status

Skip a test for various reasons

Locate a file in the testing directory

Find reporter object given name or object.

is_informative_error

Is an error informative?

Superseded skip functions

testthat_results

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

testthat_tolerance

Default numeric tolerance

MinimalReporter

Report minimal results as compactly as possible

Report results for R CMD check

Fail if any tests fail

RStudioReporter

Report results to RStudio

ProgressReporter

Report progress interactively

LocationReporter

Test reporter: location

Capture test results and metadata

Report results in jUnit XML format

Run multiple reporters at the same time

Interactively debug failing tests

Capture output to console

TeamcityReporter

Report results in Teamcity format

capture_condition

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

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

Silently collect and all expectations

Manage test reporting

SummaryReporter

Report a summary of failures