r-testthat — Claude Code skill for R package tests
The r-testthat Claude Code skill guides test writing and organization for R packages using testthat version 3 or later. The agent loads it for new tests or revisions to existing ones.
MIT 182 installs ★ 574 updated 2026-10-15
npx skills add posit-dev/skills --skill r-testthat -a claude-codeWhat r-testthat does
The skill explains how to arrange testthat files to match package code and group checks by behavior. It covers expectations for values, errors, and warnings, along with the BDD style built around describe() and it().
Tests should carry their own setup and keep side effects contained; withr provides cleanup helpers. The material also covers fixtures and snapshots for complex output. For running a full suite, it describes devtools::test() and devtools::check(). The package tests need testthat version 3 or later; cleanup examples use withr.
What it helps with
- organize test files to mirror an R package
- check function values, errors, and warnings
- group behavior checks with
describe()andit() - clean up state changes after a test using
withr - compare complex output with snapshots
Example prompts for the agent
- Help me write R package tests with
testthatversion 3. - Organize tests under
tests/testthat/to match functions inR/. - Add BDD checks with
describe()andit(), and usewithrfor cleanup.
How to install r-testthat
1Skills CLI (Vercel)
npx skills add posit-dev/skills --skill r-testthat -a claude-code2Manually: put the files in place
~/.claude/skills/r-testthat/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/r-testthat/
1Skills CLI (Vercel)
npx skills add posit-dev/skills --skill r-testthat -a codex2Manually: put the files in place
.agents/skills/r-testthat/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add posit-dev/skills --skill r-testthat -a cursor2Manually: put the files in place
.cursor/skills/r-testthat/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install posit-dev/skills r-lib/r-testthat/SKILL.md2Manually: put the files in place
.github/skills/r-testthat/SKILL.md1Skills CLI (Vercel)
npx skills add posit-dev/skills --skill r-testthat -a gemini-cli2Platform CLI
gemini skills install https://github.com/posit-dev/skills --path r-lib/r-testthatManually: put the files in place
.devin/skills/r-testthat/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add posit-dev/skills --skill r-testthat -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about r-testthat
How do I install r-testthat in Claude Code?
Run npx skills add posit-dev/skills --skill r-testthat -a claude-code. The skill file is installed at ~/.claude/skills/r-testthat/SKILL.md.
What does r-testthat do?
It helps write and arrange R package tests with testthat version 3 or later. Topics include expectations, BDD organization, fixtures, snapshots, and side-effect cleanup with withr.
How does r-testthat structure BDD tests?
Use describe() to group specifications for a component and it() for an individual behavior. The groups can be nested.
Source text
SKILL.md · MIT
---
name: r-testthat
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.
metadata:
author: Garrick Aden-Buie (@gadenbuie)
version: "1.1"
license: MIT
---
# 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
Three scales of testing:
**Micro** (interactive development):
```r
devtools::load_all()
expect_equal(foofy(...), expected)
```
**Mezzo** (single file):
```r
testthat::test_file("tests/testthat/test-foofy.R")
# RStudio: Ctrl/Cmd + Shift + T
```
**Macro** (full suite):
```r
devtools::test() # Ctrl/Cmd + Shift + T
devtools::check() # Ctrl/Cmd + Shift + E
```
## Core Expectations
### Equality
```r
expect_equal(10, 10 + 1e-7) # Allows numeric tolerance
expect_identical(10L, 10L) # Exact match required
expect_all_equal(x, expected) # Every element matches (v3.3.0+)
```
### Errors, Warnings, Messages
```r
expect_error(1 / "a")
expect_error(bad_call(), class = "specific_error_class")
expect_no_error(valid_call())
expect_warning(deprecated_func())
expect_no_warning(safe_func())
expect_message(informative_func())
expect_no_message(quiet_func())
```
### Pattern Matching
```r
expect_match("Testing is fun!", "Testing")
expect_match(text, "pattern", ignore.case = TRUE)
```
### Structure and Type
```r
expect_length(vector, 10)
expect_type(obj, "list")
expect_s3_class(model, "lm")
expect_s4_class(obj, "MyS4Class")
expect_r6_class(obj, "MyR6Class") # v3.3.0+
expect_shape(matrix, c(10, 5)) # v3.3.0+
```
### Sets and Collections
```r
expect_setequal(x, y) # Same elements, any order
expect_contains(fruits, "apple") # Subset check (v3.2.0+)
expect_in("apple", fruits) # Element in set (v3.2.0+)
expect_disjoint(set1, set2) # No overlap (v3.3.0+)
```
### Logical
```r
expect_true(condition)
expect_false(condition)
expect_all_true(vector > 0) # All elements TRUE (v3.3.0+)
expect_all_false(vector < 0) # All elements FALSE (v3.3.0+)
```
## Design Principles
### 1. Self-Sufficient Tests
Each test should contain all setup, execution, and teardown code:
```r
# Good: self-contained
test_that("foofy() works", {
data <- data.frame(x = 1:3, y = letters[1:3])
result <- foofy(data)
expect_equal(result$x, 1:3)
})
# Bad: relies on ambient state
dat <- data.frame(x = 1:3, y = letters[1:3])
test_that("foofy() works", {
result <- foofy(dat) # Where did 'dat' come from?
expect_equal(result$x, 1:3)
})
```
### 2. Self-Contained Tests (Cleanup Side Effects)
Use `withr` to manage state changes:
```r
test_that("function respects options", {
withr::local_options(my_option = "test_value")
withr::local_envvar(MY_VAR = "test")
withr::local_package("jsonlite")
result <- my_function()
expect_equal(result$setting, "test_value")
# Automatic cleanup after test
})
```
**Common withr functions:**
- `local_options()` - Temporarily set options
- `local_envvar()` - Temporarily set environment variables
- `local_tempfile()` - Create temp file with automatic cleanup
- `local_tempdir()` - Create temp directory with automatic cleanup
- `local_package()` - Temporarily attach package
### 3. Plan for Test Failure
Write tests assuming they will fail and need debugging:
- Tests should run independently in fresh R sessions
- Avoid hidden dependencies on earlier tests
- Make test logic explicit and obvious
### 4. Repetition is Acceptable
Repeat setup code in tests rather than factoring it out. Test clarity is more important than avoiding duplication.
### 5. Use `devtools::load_all()` Workflow
During development:
- Use `devtools::load_all()` instead of `library()`
- Makes all functions available (including unexported)
- Automatically attaches testthat
- Eliminates need for `library()` calls in tests
## Snapshot Testing
For complex output that's difficult to verify programmatically, use snapshot tests. See [references/snapshots.md](references/snapshots.md) for complete guide.
**Basic pattern:**
```r
test_that("error message is helpful", {
expect_snapshot(
error = TRUE,
validate_input(NULL)
)
})
```
Snapshots stored in `tests/testthat/_snaps/`.
**Workflow:**
```r
devtools::test() # Creates new snapshots
testthat::snapshot_review('name') # Review changes
testthat::snapshot_accept('name') # Accept changes
```
## Test Fixtures and Data
Three approaches for test data:
**1. Constructor functions** - Create data on-demand:
```r
new_sample_data <- function(n = 10) {
data.frame(id = seq_len(n), value = rnorm(n))
}
```
**2. Local functions with cleanup** - Handle side effects:
```r
local_temp_csv <- function(data, env = parent.frame()) {
path <- withr::local_tempfile(fileext = ".csv", .local_envir = env)
write.csv(data, path, row.names = FALSE)
path
}
```
**3. Static fixture files** - Store in `fixtures/` directory:
```r
data <- readRDS(test_path("fixtures", "sample_data.rds"))
```
See [references/fixtures.md](references/fixtures.md) for detailed fixture patterns.
## Mocking
Replace external dependencies during testing using `local_mocked_bindings()`. See [references/mocking.md](references/mocking.md) for comprehensive mocking strategies.
**Basic pattern:**
```r
test_that("function works with mocked dependency", {
local_mocked_bindings(
external_api = function(...) list(status = "success", data = "mocked")
)
result <- my_function_that_calls_api()
expect_equal(result$status, "success")
})
```
## Common Patterns
### Testing Errors with Specific Classes
```r
test_that("validation catches errors", {
expect_error(
validate_input("wrong_type"),
class = "vctrs_error_cast"
)
})
```
### Testing with Temporary Files
```r
test_that("file processing works", {
temp_file <- withr::local_tempfile(
lines = c("line1", "line2", "line3")
)
result <- process_file(temp_file)
expect_equal(length(result), 3)
})
```
### Testing with Modified Options
```r
test_that("output respects width", {
withr::local_options(width = 40)
output <- capture_output(print(my_object))
expect_lte(max(nchar(strsplit(output, "\n")[[1]])), 40)
})
```
### Testing Multiple Related Cases
```r
test_that("str_trunc() handles all directions", {
trunc <- function(direction) {
str_trunc("This string is moderately long", direction, width = 20)
}
expect_equal(trunc("right"), "This string is mo...")
expect_equal(trunc("left"), "...erately long")
expect_equal(trunc("center"), "This stri...ely long")
})
```
### Custom Expectations in Helper Files
```r
# In tests/testthat/helper-expectations.R
expect_valid_user <- function(user) {
expect_type(user, "list")
expect_named(user, c("id", "name", "email"))
expect_type(user$id, "integer")
expect_match(user$email, "@")
}
# In test file
test_that("user creation works", {
user <- create_user("[email protected]")
expect_valid_user(user)
})
```
## File System Discipline
**Always write to temp directory:**
```r
# Good
output <- withr::local_tempfile(fileext = ".csv")
write.csv(data, output)
# Bad - writes to package directory
write.csv(data, "output.csv")
```
**Access test fixtures with `test_path()`:**
```r
# Good - works in all contexts
data <- readRDS(test_path("fixtures", "data.rds"))
# Bad - relative paths break
data <- readRDS("fixtures/data.rds")
```
## Advanced Topics
For advanced testing scenarios, see:
- **[references/bdd.md](references/bdd.md)** - BDD-style testing with describe/it, nested specifications, test-first workflows
- **[references/snapshots.md](references/snapshots.md)** - Snapshot testing, transforms, variants
- **[references/mocking.md](references/mocking.md)** - Mocking strategies, webfakes, httptest2
- **[references/fixtures.md](references/fixtures.md)** - Fixture patterns, database fixtures, helper files
- **[references/advanced.md](references/advanced.md)** - Skipping tests, secrets management, CRAN requirements, custom expectations, parallel testing
## testthat 3 Modernizations
When working with testthat 3 code, prefer modern patterns:
**Deprecated → Modern:**
- `context()` → Remove (duplicates filename)
- `expect_equivalent()` → `expect_equal(ignore_attr = TRUE)`
- `with_mock()` → `local_mocked_bindings()`
- `is_null()`, `is_true()`, `is_false()` → `expect_null()`, `expect_true()`, `expect_false()`
**New in testthat 3:**
- Edition system (`Config/testthat/edition: 3`)
- Improved snapshot testing
- `waldo::compare()` for better diff output
- Unified condition handling
- `local_mocked_bindings()` works with byte-compiled code
- Parallel test execution support
## Quick Reference
**Initialize:** `usethis::use_testthat(3)`
**Run tests:** `devtools::test()` or Ctrl/Cmd + Shift + T
**Create test file:** `usethis::use_test("name")`
**Review snapshots:** `testthat::snapshot_review()`
**Accept snapshots:** `testthat::snapshot_accept()`
**Find slow tests:** `devtools::test(reporter = "slow")`
**Shuffle tests:** `devtools::test(shuffle = TRUE)`
© Garrick Aden-Buie (@gadenbuie) · MIT · posit-dev/skills