testthatdocs (version 1.0.23)

document_file: Generate idempotent listings of test_that() titles with sections

Description

Scans an R text file for test_that() calls, generates a global listing and per-section listings as roxygen comments, and inserts them right after the corresponding markers. The function is idempotent: it only replaces content between existing @testsList and @testsSection markers and leaves other code/comments unchanged. If section headers are given using a plain-text prefix (e.g., "# -"), they are converted to roxygen markers #' @testsSection (with any following text treated as the section title).

Usage

document_file(
  path,
  section_prefix = "# -",
  template = c("simple", "advanced", "full", "custom"),
  global_fmt = NULL,
  section_fmt = NULL,
  encoding = "UTF-8",
  backup = TRUE,
  write = TRUE
)

Value

A list with components:

• text: the final modified text (character vector, one element per line)

• listing: data frame of discovered tests with columns g, s, i, l (final line), title_raw, section_title.

• written: logical, whether the file was written

• backup: path to backup file (or NULL)

Arguments

path

Character. Path to the text file to process (typically a test file).

section_prefix

Character scalar. Lines starting with this prefix denote sections and are converted to #' @testsSection. Default "# -".

template

One of c("simple", "advanced", "custom"). Controls the default numbering format(s). Default "simple".

global_fmt

Character. Numbering template for the global listing. Uses placeholders {g}, {s}, {i}, {l}. If NULL, it is derived from template.

section_fmt

Character. Numbering template for section listings. If NULL, it is derived from template.

encoding

File encoding for reading and writing. Default "UTF-8".

backup

Logical. If TRUE, save a timestamped backup before overwriting. Default TRUE.

write

Logical. If TRUE, write changes back to path. If FALSE, return the would-be modified text without writing. Default TRUE.

Details

The title extracted from test_that() is the first argument as a raw expression. If that argument is a single, quoted string (single/double/backtick), the outer quotes are stripped for cleaner listings. If it is constructed via functions like paste() or glue::glue(), the raw expression is listed without evaluation (and inner quotes remain).

Numbering is customizable via templates using placeholders:

• {g} – global incremental index across all tests

• {s} – section index (1-based, order of appearance)

• {i} – local index within a section (1-based)

• {l} – line index (line number in the final, modified text)

• aliases: {local} \(\rightarrow\) {i}, {line} \(\rightarrow\) {l}

Two presets are available via template:

• "simple" → "{g}"

• "advanced" → "{g}.{s}.{i}"

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

You may fully override formats using global_fmt and section_fmt.

After inserting listings, the file is rescanned to compute the final test_that() line numbers reported in the returned data frame.

Examples

if (FALSE) {
  res <- document_file("tests/testthat/test-example.R",
                                section_prefix = "# -",
                                template = "advanced")
  res$listing
}