# R Testthat

Best practices for writing R package tests with testthat version 3+.

- Repository: https://github.com/posit-dev/skills (551 stars)
- Category: Design
- License: MIT
- Last updated: 2026-10-28
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add posit-dev/skills --skill r-testthat -g -a claude-code -y`
Codex: `npx skills add posit-dev/skills --skill r-testthat -g -a codex -y`
Cursor: `npx skills add posit-dev/skills --skill r-testthat -g -a cursor -y`
Gemini CLI: `npx skills add posit-dev/skills --skill r-testthat -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add posit-dev/skills`

## Description

Best practices for writing R package tests with testthat version 3+. Use this skill when writing or organizing tests for an R package or when improving existing tests that use testthat. It covers test structure and expectations, self-sufficient test design, proper cleanup with withr, fixtures, mocking external dependencies, snapshot testing, and BDD-style describe/it patterns.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Testing R Packages with testthat

Modern best practices for R package testing using testthat 3+.

## Initial Setup

Initialize testing with testthat 3rd edition:

```r
usethis::use_testthat(3)
```

This creates `tests/testthat/` directory, adds testthat to `DESCRIPTION` Suggests with `Config/testthat/edition: 3`, and creates `tests/testthat.R`.

## File Organization

**Mirror package structure:**
- Code in `R/foofy.R` → tests in `tests/testthat/test-foofy.R`
- Use `usethis::use_r("foofy")` and `usethis::use_test("foofy")` to create paired files

**Special files:**
- `helper-*.R` - Helper functions and custom expectations, sourced before tests
- `setup-*.R` - Run during `R CMD check` only, not during `load_all()`
- `fixtures/` - Static test data files accessed via `test_path()`

## Test Structure

Tests follow a three-level hierarchy: **File → Test → Expectation**

### Standard Syntax

```r
test_that("descriptive behavior", {
  result <- my_function(input)
  expect_equal(result, expected_value)
})
```

**Test descriptions** should read naturally and describe behavior, not implementation.

### BDD Syntax (describe/it)

For behavior-driven development, use `describe()` and `it()`:

```r
describe("matrix()", {
  it("can be multiplied by a scalar", {
    m1 <- matrix(1:4, 2, 2)
    m2 <- m1 * 2
    expect_equal(matrix(1:4 * 2, 2, 2), m2)
  })

  it("can be transposed", {
    m <- matrix(1:4, 2, 2)
    expect_equal(t(m), matrix(c(1, 3, 2, 4), 2, 2))
  })
})
```

**Key features:**
- `describe()` groups related specifications for a component
- `it()` defines individual specifications (like `test_that()`)
- Supports nesting for hierarchical organization
- `it()` without code creates pending test placeholders

**Use `describe()` to verify you implement the right things, use `test_that()` to ensure you do things right.**

See [references/bdd.md](references/bdd.md) for comprehensive BDD patterns, nested specifications, and test-first workflows.

## Running Tests

The rest: https://github.com/posit-dev/skills/blob/HEAD/r-lib/r-testthat/SKILL.md