Package {roxyreqs}

roxyreqs: 'roxygen2'-Style Metadata for Test Cases and Function Documentation

Description

Extends 'roxygen2' to support '@meta' tags for documenting 'testthat' test cases and function specifications. Includes a custom 'JUnit' reporter that exports test metadata as XML properties and validation functions to ensure all exported functions and tests contain required tags. Designed for traceability between requirements and tests in regulated industries such as pharma and finance.

Author(s)

Maintainer: Moritz Lang moritz.n.lang@gmail.com

Authors:

• Mario Annau mario.annau@gmail.com

Other contributors:

• Doug Kelkhoff doug.kelkhoff@gmail.com [contributor]

• Szymon Maksymiuk sz.maksymiuk@gmail.com [contributor]

See Also

Useful links:

• https://github.com/mnlang/roxyreqs

• Report bugs at https://github.com/mnlang/roxyreqs/issues

Test reporter: summary of errors in JUnit XML format.

Description

This reporter includes detailed results about each test and summaries, written to a file (or stdout) in JUnit XML format. This can be read by the Jenkins Continuous Integration System to report on a dashboard etc. Requires the xml2 package.

Details

To fit into the JUnit structure, context() becomes the ⁠<testsuite>⁠ name as well as the base of the ⁠<testcase> classname⁠. The test_that() name becomes the rest of the ⁠<testcase> classname⁠. The deparsed expect_that() call becomes the ⁠<testcase>⁠ name. On failure, the message goes into the ⁠<failure>⁠ node message argument (first line only) and into its text content (full message).

Execution time and some other details are also recorded.

Tests without ⁠@meta⁠ roxygen blocks produce test cases with an empty ⁠<properties/>⁠ node. Use check_meta_test() to validate that all required tags are present.

References for the JUnit XML format: http://llg.cubic.org/docs/junit/

Super classes

testthat::Reporter -> testthat::JunitReporter -> JunitReporterMeta

Public fields

Methods

Public methods

• JunitReporterMeta$elapsed_time()

• JunitReporterMeta$reset_suite()

• JunitReporterMeta$start_reporter()

• JunitReporterMeta$start_file()

• JunitReporterMeta$start_test()

• JunitReporterMeta$start_context()

• JunitReporterMeta$end_context()

• JunitReporterMeta$add_result()

• JunitReporterMeta$end_reporter()

• JunitReporterMeta$clone()

Method elapsed_time()

Return elapsed time since last call and reset timer.

Usage

JunitReporterMeta$elapsed_time()

Returns

Elapsed time in seconds.

Method reset_suite()

Reset suite counters to zero.

Usage

JunitReporterMeta$reset_suite()

Method start_reporter()

Initialize the reporter, create XML document.

Usage

JunitReporterMeta$start_reporter()

Method start_file()

Start processing a test file. Parses roxygen2 blocks.

Usage

JunitReporterMeta$start_file(file)

Arguments

Method start_test()

Called at the start of each test.

Usage

JunitReporterMeta$start_test(context, test)

Arguments

Method start_context()

Start a new test suite context.

Usage

JunitReporterMeta$start_context(context)

Arguments

Method end_context()

Finalize a test suite context. Writes counts and time.

Usage

JunitReporterMeta$end_context(context)

Arguments

Method add_result()

Add a test result. Matches ⁠@meta⁠ tags from roxygen2 blocks and writes them as XML properties.

Usage

JunitReporterMeta$add_result(context, test, result)

Arguments

Method end_reporter()

Write the XML document to the output destination.

Usage

JunitReporterMeta$end_reporter()

Method clone()

The objects of this class are cloneable with this method.

Usage

JunitReporterMeta$clone(deep = FALSE)

Arguments

Meta information

Id: URS01.FS007

Compliance Risk: low

Implementation Complexity: medium

Test Scope: medium

Examples

## Not run: 
testthat::test_local(path = "inst/example.pkg", reporter = JunitReporterMeta)

## End(Not run)

Check Metadata Documentation

Description

A suite of functions to validate metadata documentation in Rd and test files.

Meta tags follow the format ⁠@meta key value⁠ where key can be any user-defined identifier. Built-in tags for function documentation include id, compliance_risk, and implementation_complexity. For test files, the default required tags are author, reviewer, review_date, and description. Custom tags can be added and validated by passing them to the check_rd_tag_exist or check_test_tag_exist parameters.

This function combines multiple checks to ensure metadata in your Rd and test files meets required standards for completeness, uniqueness, and documentation quality. The following checks are included:

• check_meta_rd(): Checks for missing metadata tags in Rd files.

• check_meta_unique_ids(): Ensures the 'Id' metadata tag in Rd files is unique.

• check_meta_undocumented_test(): Validates that all test_that test cases are properly documented.

• check_meta_test(): Verifies that test case documentation contains all required metadata tags.

Usage

check_meta(
  files_rd = list.files("man", pattern = "*.Rd", full.names = TRUE),
  files_test = list.files("tests/testthat", pattern = "^test-.*\\.R$", full.names =
    TRUE),
  check_rd_tag_exist = c("Id", "Compliance Risk", "Implementation Complexity",
    "Test Scope"),
  check_test_tag_exist = c("author", "reviewer", "review_date", "description"),
  check_rd_tag_unique = "Id",
  exclude_package_rd = TRUE,
  concise = TRUE,
  print_error = FALSE
)

check_meta_test(
  files_test = list.files("tests/testthat", pattern = "^test-.*\\.R$", full.names =
    TRUE),
  check_test_tag_exist = c("author", "reviewer", "review_date", "description"),
  concise = FALSE,
  print_error = FALSE
)

check_meta_undocumented_test(
  files_test = list.files("tests/testthat", pattern = "^test-.*\\.R$", full.names =
    TRUE),
  concise = FALSE,
  print_error = FALSE
)

check_meta_rd(
  files_rd = list.files("man", pattern = "*.Rd", full.names = TRUE),
  check_rd_tag_exist = c("Id", "Compliance Risk", "Implementation Complexity",
    "Test Scope"),
  exclude_package_rd = TRUE,
  concise = FALSE,
  print_error = FALSE
)

check_meta_unique_ids(
  files_rd = list.files("man", pattern = "*.Rd", full.names = TRUE),
  check_rd_tag_unique = "Id",
  exclude_package_rd = TRUE,
  concise = FALSE,
  print_error = FALSE
)

Arguments

Value

• check_meta(): A named list with results from each sub-check (invisibly).

Meta information

Id: URS01.FS005

Compliance Risk: low

Implementation Complexity: low

Test Scope: low

Parse and format roxygen2 meta tags

Description

S3 methods that extend roxygen2 to support ⁠@meta⁠ tags in function and test documentation. Tags follow the format ⁠@meta key value⁠ where key can be any user-defined identifier (underscores become spaces, title-cased in output).

Usage

## S3 method for class 'roxy_tag_meta'
roxy_tag_parse(x)

## S3 method for class 'roxy_tag_meta'
roxy_tag_rd(x, base_path, env)

## S3 method for class 'rd_section_meta'
merge(x, y, ...)

## S3 method for class 'rd_section_meta'
format(x, ...)

Arguments

Details

format.rd_section_meta automatically computes a ⁠Test Scope⁠ value from ⁠Compliance Risk⁠ and ⁠Implementation Complexity⁠ using an internal scopemap matrix. Tags are reordered with Id, ⁠Compliance Risk⁠, ⁠Implementation Complexity⁠, and ⁠Test Scope⁠ first, followed by any custom tags.

Meta information

Id: URS01.FS011

Compliance Risk: low

Implementation Complexity: low

Test Scope: low

Move macro (meta) fragment right after arguments

Description

Move macro (meta) fragment right after arguments

Usage

move_macro_first(x, rd_tag = "\\title", offset = 1L)

Arguments

Value

transformed Rd object

Meta information

Id: URS01.FS012

Compliance Risk: low

Implementation Complexity: low

Test Scope: low

Parse Metadata from Rd Files

Description

Parse Metadata from Rd Files

Usage

parse_rd_meta(filepath)

Arguments

Value

data.frame containing one column for each meta tag and one row per filepath.

Meta information

Id: URS01.FS006

Compliance Risk: low

Implementation Complexity: low

Test Scope: low