One-click documentation for testthat

Rafal Urniaz, PhD

Installation

install.packages("testthatdocs")

Usage

testthatdocs::document()

Example

testthatdocs::document(template = "advanced")

# This is a demo test file

# - Section A
context("demo")
test_that("A: literal one", {
  expect_true(TRUE)
})

test_that(paste("A:", 2), {
  expect_true(TRUE)
})

# - Section B
test_that(glue::glue("B-{x}", x = 3), {
  expect_true(TRUE)
})

test_that("Outside", {
  expect_true(TRUE)
})

#' @testsList
#' @testsItem 1.1.1 A: literal one
#' @testsItem 2.1.2 paste("A:", 2)
#' @testsItem 3.2.1 glue::glue("B-{x}", x = 3)
#' @testsItem 4.2.2 Outside
# This is a demo test file

#' @testsSection Section A
#' @testsItem 1.1.1 A: literal one
#' @testsItem 2.1.2 paste("A:", 2)
context("demo")
test_that("A: literal one", {
  expect_true(TRUE)
})

test_that(paste("A:", 2), {
  expect_true(TRUE)
})

#' @testsSection Section B
#' @testsItem 3.2.1 glue::glue("B-{x}", x = 3)
#' @testsItem 4.2.2 Outside
test_that(glue::glue("B-{x}", x = 3), {
  expect_true(TRUE)
})

test_that("Outside", {
  expect_true(TRUE)
})

[!NOTE]

• Generates a global list of tests and per-section test listings as roxygen comments.
• Inserts the generated listings immediately after the corresponding markers.

[!TIP]

• The function is idempotent:
  • Only replaces content between existing @testsList and @testsSection markers.
  • Leaves all other code and comments unchanged.
• If section headers are provided using a plain-text prefix (e.g. # -):
  • They are automatically converted to roxygen markers #' @testsSection.
  • Any text following the prefix is treated as the section title.

Numbering and Templates

Numbering is customisable via templates that use placeholders:

• {g} – global incremental index across all tests
• {s} – section index (1-based, in order of appearance)
• {i} – local index within a section (1-based)
• {l} – line index (line number in the final, modified text)

The following templates are available:

• "simple" → {g}
• "advanced" → {g}.{s}.{i}
• "full" → {g}.{s}.{i}.{l}

You can fully override the numbering format by providing custom values for:

• global_fmt
• section_fmt

This allows complete control over how numbers are generated.