Quick Start: Generating Idempotent test_that() Listings with Sections

Overview

This vignette demonstrates a robust, idempotent workflow for generating a roxygen2-style inventory of all test_that() calls in one test file. The function:

• Extracts the raw first argument of test_that() as the title (without evaluating expressions).
• Converts plain-text section markers (default "# -" prefix) to roxygen markers #' @testsSection.
• Inserts a global listing after #' @testsList and per-section listings after each #' @testsSection.
• Uses customizable numbering templates: {g} (global), {s} (section), {i} (local within section), {l} (final line number).
• Is idempotent: only @testsItem blocks immediately following listing markers are regenerated; all other code and comments remain unchanged.
• Optionally backs up the original file and supports a dry-run mode.
• Strips outer quotes for plain string titles, while preserving expressions like paste("x", y).

Quick Start

library(testthatdocs)

res <- document_file(
  path = system.file("examples", "tests_sample_before.R", package="testthatdocs"),
  section_prefix = "# -",
  template = "advanced",   # or "simple"
  encoding = "UTF-8",
  backup = TRUE,
  write = TRUE
)

# Summary of tests 
res$listing

# Modified test file 
res$text

```

The result includes:

• text: the modified file as a character vector (one line per element)
• listing: a data frame with columns g, s, i, l, title_raw, section_title
• written: whether the file was written
• backup: backup path (if created)