testthatdocs (version 1.0.23)

document: Recursively generate test listings across a testthat tree

Description

Walks the tests/testthat directory (by default), finds test files, and runs document_file on each matching file. All options from document_file() are available here as pass-through parameters.

Usage

document(
  root = "tests/testthat",
  pattern = "^[Tt]est.*\\.[rR]$",
  recurse = TRUE,
  exclude = c("testthat.R"),
  section_prefix = "# -",
  template = c("simple", "advanced", "custom"),
  global_fmt = NULL,
  section_fmt = NULL,
  encoding = "UTF-8",
  backup = TRUE,
  write = TRUE,
  quiet = FALSE
)

Value

A list with components:

• files: character vector of processed file paths

• results: named list of tests_listing_result objects per file

• listing: combined data frame with a file column

• backups: character vector of backup paths (for files that were written)

Arguments

root

Character. Root directory to search. Default "tests/testthat".

pattern

Regular expression used with list.files(..., pattern=) to select test files. Default matches typical testthat files: "^[Tt]est.*\.[rR]$".

recurse

Logical. Whether to search subdirectories recursively. Default TRUE.

exclude

Character vector of basenames to exclude (e.g., "testthat.R"). Default c("testthat.R").

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.

quiet

Logical. If FALSE (default), prints progress messages.

Examples

if (FALSE) {
  all_res <- document(
    root = "tests/testthat",
    template = "advanced",
    backup = TRUE,
    write = TRUE
  )
  head(all_res$listing)
}