Title:	Assessing Package Test Reliability and Quality
Version:	2.0.0
Description:	A reliable and validated tool that calculates unit test coverage for R packages with standard testing frameworks and non-standard testing frameworks.
License:	GPL-2 | GPL-3 [expanded from: GPL (≥ 2)]
BugReports:	https://github.com/Sanofi-Public/test.assessr/issues
Depends:	R (≥ 4.1.0)
Imports:	callr, checkmate, covr, dplyr, fs, jsonlite, pkgload, remotes, rlang, rmarkdown, RUnit, stringr (≥ 1.5.0), testthat (≥ 3.0.0), tinytest, tidyr, utils, withr
Suggests:	devtools, DT, here, kableExtra (≥ 1.4.0), knitr, methods, R6, S7, roxygen2, tidyselect, tools, mockery
Encoding:	UTF-8
RoxygenNote:	7.3.3
Config/testthat/edition:	3
Config/build/clean-inst-doc:	false
VignetteBuilder:	knitr
NeedsCompilation:	no
Packaged:	2026-04-16 11:11:39 UTC; u1004798
Author:	Edward Gillian [cre, aut], Hugo Bottois [aut], Paulin Charliquart [aut], Andre Couturier [aut], Sanofi [cph, fnd]
Maintainer:	Edward Gillian <edward.gillian-ext@sanofi.com>
Repository:	CRAN
Date/Publication:	2026-04-16 11:50:02 UTC

Check for skipped or errored test files (BiocGenerics)

Description

This internal function attempts to run test files mapped to source files and identifies any that produce warnings or errors. It does not handle 'testit'.

Usage

check_covr_skip_bioc_nstf(pkg_source_path, mapping, test_path)

Arguments

Value

A data frame listing test files and any issues encountered.

Check for skipped or errored test files (non-testit)

Description

This internal function attempts to run test files mapped to source files and identifies any that produce warnings or errors. It does not handle 'testit'.

Usage

check_covr_skip_nstf(
  pkg_source_path,
  mapping,
  base_dir = file.path(pkg_source_path, "tests")
)

Arguments

Value

A data frame listing test files and any issues encountered.

Check for skipped or errored test files (BiocGenerics)

Description

This internal function attempts to run test files mapped to source files and identifies any that produce warnings or errors. It does not handle 'testit'.

Usage

check_covr_skip_runit_nstf(pkg_source_path, mapping, test_path)

Arguments

Value

A data frame listing test files and any issues encountered.

Run testit tests individually, capturing all warnings and errors, with dynamic package root detection

Description

Run testit tests individually, capturing all warnings and errors, with dynamic package root detection

Usage

check_covr_skip_testit(pkg_name, mapping, test_path)

Arguments

Value

A data frame with test_file and issue_type columns

See Also

Other nstf_utility: create_base_tests_coverage(), create_nstf_covr_list(), create_tinytest_coverage(), get_nstf_test_path(), get_source_test_mapping_nstf(), restrict_test_paths_to_framework(), run_covr_skip_nstf()

Check Which Elements Exist in a List

Description

This internal function checks whether specified elements exist in a given list and returns two vectors: elements that exist and elements that do not. When nested = TRUE and x has results (multi-framework), checks inside each x$results$<framework>.

Usage

check_elements_simple(x, elems, nested = FALSE)

Arguments

Value

A list with:

present

Character vector of elements that exist.

missing

Character vector of elements that do not exist (top-level only).

by_framework

Named list (framework -> present elements), when nested.

Check for tests/testthat and _snaps folder and count golden tests

Description

Check for tests/testthat and _snaps folder and count golden tests

Usage

check_pkg_tests_and_snaps(pkg_source_path)

Arguments

Value

A list with: - 'has_testthat': Does tests/testthat exist? - 'has_testit': Does tests/testit exist? - 'has_tests_base': Do tests exist in tests subdirectory? - 'has_BioG_test': Do BioGenerics tests exist in inst/tests subdirectory? - 'has_RUnit_test': Do RUnit tests exist (inst/unitTests; optionally tests/run_unitTests.R)? - 'bioc_unit_tests_dir' : location of BioGenerics unit tests - 'bioc_run_ut_path': location of BioGenerics 'run_unitTests.R' - 'has_snaps': Does _snaps exist inside tests/testthat? - 'n_golden_tests': Number of snapshot files inside _snaps - 'n_test_files': Number of test-*.R files inside tests/testthat - 'has_tinytest' : Does tinytest exist? - 'tinytest_dir' : location of tinytest unit tests - 'tinytest_runner_paths' : location of tinytest runner paths - 'n_tinytest_files' : Number of test_*.R files under inst/tinytest - 'has_data_table_tests': Do data.table tests exist in directories? - 'data_table_tests_path' : location of data.table unit tests

Clean up cov environment and return NULL

Description

This internal utility function is used to clean up the cov environment by removing all objects and optionally displaying a message before returning 'NULL'. It is primarily used within 'run_coverage_base()' to ensure consistent cleanup in error-handling scenarios.

Usage

cleanup_and_return_null(msg = NULL, env = cov_env)

Arguments

Value

NULL (invisibly)

Compute aggregate total coverage across multiple frameworks

Description

Compute aggregate total coverage across multiple frameworks

Usage

compute_multi_framework_total(per_framework)

Arguments

Value

Numeric. Mean of per-framework total_cov (0-100), or 0 if none.

Compute wrapper data.table test files to run for coverage (internal)

Description

Selects and sanitizes the list of **wrapper** test files to execute during coverage, supporting both the standard 'tests/' layout and the 'testit' layout ('tests/testit/'). When 'pkg_name' is '"data.table"', the function adds package-aware behavior: it falls back to 'tests/main.R' if the mapping yields no existing files and optionally prioritizes 'froll.R' so rolling function tests run early.

Usage

compute_test_files_clean_dt(
  pkg_name,
  pkg_source_path,
  clean_mapping,
  test_pkg_data,
  skip_tests = NULL
)

Arguments

Details

This helper **only resolves file paths**; it does **not** modify the evaluation environment, copy/mirror test assets, or toggle data.table's test harness mode. Any package-specific preparation (e.g., mirroring 'inst/tests/' to 'tests/' or exposing 'test.data.table()' in dev mode) must be handled elsewhere (see 'prepare_tests_for_package()').

Value

'character()' - **normalized**, de-duplicated vector of wrapper file paths that **exist** on disk. May be zero length if no candidates exist and no fallback is available.

Compute approximate total coverage combining line coverage and test breadth

Description

Computes an approximate "total coverage" metric by combining: 1) line coverage percentage ('percent_cov', 0–100), and 2) a conservative proxy for breadth of tests based on counts of passing test files, functions without tests, and skipped test files.

The final metric scales line coverage (as a proportion) by the fraction of tested over total function-space, where: - 'n_testfiles' = number of passing test files (if 0, treated as 1 to avoid divide-by-zero), - 'n_no_function_tests' = number of functions lacking tests ('nrow(functions_no_tests_df)'), - 'n_skipped_files' = number of skipped test files ('length(tests_skipped)'), - 'total_functions' = 'n_tested + n_untested' with 'n_tested = max(n_testfiles, 1)', - 'total_cov' = (percent_cov / 100) * (n_tested / total_functions).

Usage

compute_total_coverage(
  percent_cov,
  functions_no_tests_df,
  tests_passing,
  tests_skipped
)

Arguments

Details

This function is intentionally conservative: - Passing test *files* are used as a proxy for tested functions. - Skipped test files contribute to "untested breadth". - If there are zero passing test files, 'n_tested' is set to 1 to avoid divide-by-zero and produce a small non-zero denominator.

Value

A named list with:

• total_cov (numeric): Approximate total coverage (proportion 0–1).

• percent_cov_round (numeric): total_cov rounded to 2 decimals (still 0–1).

• n_testfiles (integer): Count of passing test files.

• n_no_function_tests (integer): Count of functions lacking tests.

• n_skipped_files (integer): Count of skipped test files.

Convert number to abbreviation

Description

Convert number to abbreviation

Usage

convert_number_to_abbreviation(value)

Arguments

Convert number to percent

Description

Convert number to percent

Usage

convert_number_to_percent(value)

Arguments

This internal function takes named character vectors (e.g., 'tests_skipped', 'tests_passing') from a list and converts them into data frames for easier reporting or processing.

Description

This internal function takes named character vectors (e.g., 'tests_skipped', 'tests_passing') from a list and converts them into data frames for easier reporting or processing.

Usage

convert_vectors_to_df(x, elems)

Arguments

Value

A named list of data frames, where each data frame has one column:

file

The file names or paths from the original character vector.

Package-Private Coverage Environment

Description

'cov_env' is a package-internal environment used by test/coverage helpers (e.g., 'cleanup_and_return_null()') to store temporary state without ever touching the user's workspace ('.GlobalEnv'). It is created at package load time so that a binding for 'cov_env' exists *inside the locked package namespace*, which allows tests to temporarily replace its value (mock) while still complying with CRAN’s “no .GlobalEnv modifications” rule.

Usage

cov_env

Format

An object of class environment of length 0.

Details

**When is it built?** During package setup, all 'R/' files are parsed and evaluated as part of namespace loading. At that point this line is executed:

“' cov_env <- new.env(parent = baseenv()) “'

which creates the binding 'cov_env' in the package namespace **before** the namespace is locked by R. Once a namespace is locked, you cannot add or remove bindings—you may only change the *values* of existing bindings. By pre-creating 'cov_env', tests can safely and temporarily replace it (e.g., with 'testthat::local_mocked_bindings()'), because they modify an *existing* binding rather than creating a new one. (See: R’s environment/namespace locking rules and testthat’s guidance that mocked bindings must already exist.) [1](https://colinfay.me/writing-r-extensions/writing-r-documentation-files.html)[2](https://contributor.r-project.org/cran-cookbook/code_issues.html)

**Why 'parent = baseenv()'?** Using 'baseenv()' isolates lookups so they do not fall through to the user’s workspace. This keeps internal state separate and avoids accidental reads or writes to '.GlobalEnv'. [3](https://github.com/coolbutuseless/CRAN-checks)

**Testing tip:** In unit tests, you can temporarily replace this binding without editing the global environment:

“' testthat::local_mocked_bindings( .package = "yourpkg", cov_env = new.env(parent = baseenv()) ) “'

This works because the 'cov_env' *binding already exists* in the namespace; 'local_mocked_bindings()' cannot create new bindings in a locked namespace. [2](https://contributor.r-project.org/cran-cookbook/code_issues.html)

Create coverage by running base-style tests under covr (internal)

Description

Traces the package namespace with covr, then sources each test script from its own directory (so relative file references like 'load("solr.rda")' in MASS/tests work). Converts covr counters to a coverage object.

Usage

create_base_tests_coverage(pkg_source_path, pkg_name, test_files)

Arguments

Value

list(coverage = <covr coverage object>)

See Also

Other nstf_utility: check_covr_skip_testit(), create_nstf_covr_list(), create_tinytest_coverage(), get_nstf_test_path(), get_source_test_mapping_nstf(), restrict_test_paths_to_framework(), run_covr_skip_nstf()

Run Coverage While Skipping Failing Tests

Description

This function runs coverage analysis using 'covr' while temporarily commenting out known failing tests. It is intended for situations where specific tests must be skipped (e.g., due to upstream bugs or known failures) so that coverage can still be computed on remaining tests.

Usage

create_coverage_skip_stf(
  pkg_source_path,
  pkg,
  test_path = "tests/testthat",
  test_skip,
  test_map,
  cov_env
)

Arguments

Details

The function:

• sets up a temporary coverage environment,

• identifies lines to skip based on 'test_skip',

• comments out those test lines,

• runs 'covr::environment_coverage()', and

• restores the original test files on exit.

If 'test_skip' is 'NULL', failing tests must be detected elsewhere before calling this function. This function does not perform test detection; it only applies the skip mappings supplied in 'test_skip'.

Value

A coverage object (a list) returned by 'covr::environment_coverage()', filtered to remove problematic entries. If coverage fails, the function returns 'NULL'.

The returned structure typically contains:

filename

Name of the file being measured.

functions

Function-level coverage information.

linecoverage

Line-by-line execution counts.

srcref

Source references extracted for coverage.

See Also

test_dir, package_coverage, environment_coverage

Other stf_utility: map_test(), map_tests_stf(), nest_test(), run_covr_skip_stf()

create covr_list when no tests are skipped

Description

create covr_list when no tests are skipped

Usage

create_covr_list_no_skip(
  test_map,
  test_results_long,
  pkg_source_path,
  pkg,
  cov_env
)

Arguments

Value

- summary cvr object

Create an empty covr list for fallback

Description

This internal utility function returns a default coverage list structure used when test execution or mapping fails. It ensures consistent output format for downstream processing even when no valid test results are available.

Usage

create_empty_covr_list(pkg_name, error_message)

Arguments

Value

A named list containing default coverage values, the provided error message, and placeholder notes.

Create Fail Reporter

Description

Executes all tests in a given directory using 'testthat::test_dir()' and applies context fixes to ensure each test has a valid context.

Usage

create_fail_reporter(test_path, pkg, cov_env)

Arguments

Value

A list of test results with corrected contexts, or 'NULL' if an error occurs.

Generate file coverage df

Description

Generates file coverage df when errors list created.

Usage

create_file_coverage_df(file_names, file_coverage, errors, notes)

Arguments

Generate Long Summary Details

Description

Generates the Long Summary table for the HTML report.

Usage

create_long_summary_details(df)

Arguments

Create the NSTF Coverage List

Description

Internal helper that constructs the final 'covr_list' structure from a coverage object. It wraps extraction of coverage information, performs total coverage computation, and assembles all diagnostic components.

Usage

create_nstf_covr_list(
  coverage,
  pkg_name,
  no_tests_df,
  test_files_clean,
  skip_tests,
  problems
)

Arguments

Value

A named list ('covr_list') containing:

total_cov

Numeric; overall package coverage percentage.

res_cov

List; raw coverage extraction results with coverage data, errors, notes.

functions_no_tests

Data frame of functions lacking tests.

tests_skipped

Character vector of skipped test files.

tests_passing

Character vector of passing test files.

tests_problems

Character vector describing test problems.

See Also

Other nstf_utility: check_covr_skip_testit(), create_base_tests_coverage(), create_tinytest_coverage(), get_nstf_test_path(), get_source_test_mapping_nstf(), restrict_test_paths_to_framework(), run_covr_skip_nstf()

Create a Summary of Coverage Results

Description

This function extracts overall test coverage and file‑level coverage information from a covr coverage object. It provides a simplified summary for downstream reporting and scoring.

Usage

create_results_summary(cvr)

Arguments

Value

A data frame containing summary statistics, including:

total_cov

Numeric. Overall percentage of lines covered.

name

Character. File or package name associated with the coverage result.

coverage

List or data structure summarizing file‑level or element‑level coverage from the covr object.

errors

Character vector containing any coverage‑related errors (if present).

notes

Additional diagnostic notes returned by coverage processing.

The summary object is used by downstream reporting functions to generate test coverage summaries and scoring metrics.

Create Test Reporter

Description

Executes all tests in a given directory using 'testthat::test_dir()' and applies context fixes to ensure each test has a valid context.

Usage

create_test_reporter(test_path, pkg, cov_env)

Arguments

Value

A list of test results with corrected contexts, or 'NULL' if an error occurs.

Generate Test Skip Details

Description

Generates the Test Skip table for the HTML report.

Usage

create_test_skip_details(df)

Arguments

Create coverage from tinytest under covr instrumentation (internal)

Description

Instruments the package **namespace** with covr, runs all tinytest files in inst/tinytest, and returns a covr coverage object together with the tinytest results. This mirrors tinytest's execution model (expectation helpers available; tests run from each file's directory) while ensuring calls into the package namespace are traced.

Usage

create_tinytest_coverage(
  pkg_source_path,
  pkg_name,
  tiny_dir = file.path(pkg_source_path, "inst", "tinytest"),
  at_home = TRUE,
  color = FALSE
)

Arguments

Details

Intended for **source-tree** coverage of tinytest suites:

• The package namespace is traced via covr::trace_environment() so that calls made by tests to package functions are recorded for coverage.

• NOT_CRAN is set to "true" during the run (restored on exit) so tinytest at_home() logic treats the run as local.

• Test files are driven by tinytest::run_test_dir() from file.path(pkg_source_path, "inst", "tinytest").

• Coverage is built from covr's counters using covr::as_coverage().

Preconditions

• The package under test should already be loaded (e.g., pkgload::load_all(pkg_source_path)), so that asNamespace(pkg_name) exists and reflects the current source.

• The directory inst/tinytest must exist and contain test files.

Value

A list with components:

coverage

An object of class "coverage" (from covr).

tinytests

The tinytests object returned by tinytest.

See Also

Other nstf_utility: check_covr_skip_testit(), create_base_tests_coverage(), create_nstf_covr_list(), get_nstf_test_path(), get_source_test_mapping_nstf(), restrict_test_paths_to_framework(), run_covr_skip_nstf()

Detach a package if attached (internal)

Description

Safely detaches a package from the search path and optionally unloads its namespace.

Usage

detach_pkg_if_attached(pkg, unload_namespace = TRUE, quiet = TRUE)

Detect which test frameworks are present in a package

Description

Detect which test frameworks are present in a package

Usage

detect_frameworks(test_pkg_data)

Arguments

Value

Character vector of framework IDs: "testthat", "testit", "tests_base", "tinytest", "data.table", "bioconductor".

Compute untested functions from coverage using srcref spans (internal)

Description

Identifies package functions that were not executed by the provided coverage object. A function is considered untested if no line within its srcref span (from start_line to end_line) has a positive execution count in covr::tally_coverage().

Usage

dt_compute_untested_functions(pkg_name, coverage)

Arguments

Value

data.frame with one row per untested function and columns:

function_name

Function symbol in the package namespace.

file

Absolute, normalized path to the source file containing the function.

start_line

Start line (inclusive) from the function's srcref.

end_line

End line (inclusive) from the function's srcref.

Returns an empty data.frame with these columns if (a) the coverage table is empty, (b) no functions have an srcref, or (c) all functions had at least one executed line within their span.

Details

• Functions without an srcref are skipped.

• Files are matched by basename between the coverage table and the function’s srcref source path to make the join resilient to differing absolute paths in temporary build trees.

• A line is considered executed when its coverage value is a finite number greater than zero.

See Also

tally_coverage

Locate data.table wrapper test scripts (internal)

Description

Returns absolute, normalized paths to known wrapper test scripts under tests/ for a data.table source checkout. This is used to determine which wrapper files exist locally so that callers can distinguish between the canonical entrypoint tests/main.R and other wrapper scripts (e.g., froll.R, programming.R, etc.).

Usage

dt_find_wrapper_tests(pkg_source_path)

Arguments

Value

character(). A vector of existing files among the known candidates, with absolute paths normalized via normalizePath(..., winslash = "/"). The vector is empty if none of the candidates exist.

Notes

The candidate list is intentionally small and stable. If the upstream repository adds additional wrappers, extend this function’s list.

Helper to extract "R/<file>" from any path by taking the last two components

Description

Helper to extract "R/<file>" from any path by taking the last two components

Usage

extract_short_path(long_file_name)

Arguments

Value

A character string composed of the last two path components, e.g., "R/add.R"

Find R project root directory

Description

Searches upward from a starting path to locate the root of an R package or project.

Usage

find_project_root(start = getwd())

Arguments

Value

character path to project root, or NULL if not found

Fix Missing Test Contexts

Description

Ensures that each test result has a valid 'context' field. If missing or empty, the context is set to the file name (without extension).

Usage

fix_test_context(test_results)

Arguments

Value

A list of test results with updated contexts.

Generate Coverage Section (single framework)

Description

Generates the Coverage section for the HTML report from a single framework's res_cov.

Usage

generate_coverage_section(assessment_results, pkg_name)

Arguments

Generate Coverage Sections (multi-framework)

Description

Returns a named list of coverage data frames, one per framework.

Usage

generate_coverage_sections(test_results, pkg_name)

Arguments

Value

Named list of data frames (Function, Coverage, Errors, Notes).

Generate Test Details

Description

Generates the Test Details table for the HTML report.

Usage

generate_test_details(assessment_results, framework_id = NULL)

Arguments

Generate Test Summary

Description

Generates the Risk Summary table for the HTML report.

Usage

generate_test_pkg_summary(assessment_results)

Arguments

Generate HTML Report for Package Test Assessment

Description

Generates an HTML report for the package test assessment results using rmarkdown.

Usage

generate_test_report(test_results, output_dir = NULL)

Arguments

Value

Path to the generated HTML report.

Examples

## Not run: 
test_results <- get_package_coverage()
# Always provide a directory; tempdir() is convenient in examples.
generate_test_report(test_results, output_dir = tempdir())

## End(Not run)

Locate active test paths for Bioconductor RUnit layout

Description

Returns a *list* of one or more existing test directories suitable for normalization and use in subsequent mapping (e.g., 'get_source_test_mapping_nstf'). Designed to work with:

Usage

get_biocgenerics_test_paths(test_pkg_data, testdir)

Arguments

Details

path <- as.character(pkg_source_path) testdir <- file.path(path, "inst/unitTests") test_path_list <- find_biocgenerics_test_paths(test_pkg_data, testdir) test_path <- normalizePath( unlist(test_path_list, use.names = TRUE), winslash = "/", mustWork = FALSE )

Value

named list of **existing** directories (e.g., 'bioc_unitTests', 'tests_root'); if nothing is found, returns a single 'fallback' entry pointing to 'testdir'.

Extract Expectation Calls from Parsed Testthat Code

Description

This internal helper identifies expectation calls (e.g., 'expect_equal()', 'expect_true()', etc.) within parse data extracted from a testthat test file. The function locates expectation function calls by matching their token text and returns a structured data frame containing the expectation names and their corresponding source line ranges.

Usage

get_expect(parsed_data, token_text = "^expect_")

Arguments

Details

The function:

• locates all rows where the token is "SYMBOL_FUNCTION_CALL" and the text matches token_text,

• identifies the expression node corresponding to each expectation,

• extracts line ranges (line1, line2) describing where the expectation appears in the source file, and

• returns a consolidated data frame of results.

If no expectation calls are found, the function returns NULL. This helper is used internally by STF mapping functions (such as map_test() and map_tests_stf()) when constructing a full hierarchy of test blocks and expectations.

Value

A data.frame where each row corresponds to a detected expectation. The data frame contains:

expectation

Character. Name of the expectation function (e.g., "expect_equal").

line1

Integer. Starting line number of the expression.

line2

Integer. Ending line number of the expression.

Returns NULL if no matching expectations are found.

get functions with no tests

Description

get functions with no tests

Usage

get_function_no_tests(mapping_df)

Arguments

Value

no_tests_df - data frame with source files with no tests

Collect all applicable nonstandard test paths for a package (internal)

Description

Detects and returns all relevant testing directories used by an R package, combining framework-specific and filesystem-based checks. Supported layouts:

• testthat: tests/testthat/

• tinytest: inst/tinytest/ (primary location). Some packages also include a small runner under tests/ (e.g., tests/tinytest.R) which this function does not return as a path, but it will still detect inst/tinytest/.

• testit (standard): tests/testit/

• testit (nonstandard): both tests/test-ci/ and tests/test-cran/ present, using tests/ as the root

• base R tests: *.R files directly under tests/

• Bioconductor unit tests: inst/unitTests/

Usage

get_nstf_test_path(test_pkg_data, testdir)

Arguments

Details

The function returns a named list of paths for all detected testing setups. It uses both the flags contained in test_pkg_data and direct filesystem checks for robustness. If no paths are detected, the returned list contains a single entry default_tests_root = tests/.

Identical paths arising from multiple detection routes (e.g., tests/ playing multiple roles) are de-duplicated while preserving the first descriptive label. If tinytest_dir is provided and relative, it is resolved against the package root (i.e., dirname(testdir)).

Value

list. A named list of character paths to all applicable test directories found. Possible names include:

• tinytest — inst/tinytest/

• testthat — tests/testthat/

• testit — tests/testit/

• nonstandard_testit_root — tests/ (when both test-ci and test-cran exist)

• base_tests_root — tests/ (when base *.R files exist in tests/ root)

• bioc_unitTests — inst/unitTests/

• default_tests_root — tests/ (returned only if no other paths are detected)

See Also

Other nstf_utility: check_covr_skip_testit(), create_base_tests_coverage(), create_nstf_covr_list(), create_tinytest_coverage(), get_source_test_mapping_nstf(), restrict_test_paths_to_framework(), run_covr_skip_nstf()

get package test coverage

Description

simplified input to assess package for test coverage

Usage

get_package_coverage(path = NULL)

Arguments

Value

An object of class "coverage" as produced by test.assessr::run_covr_modes(). This object is a structured list containing detailed test coverage information, including:

• File-level coverage: percentage of lines covered in each file.

• Line-by-line coverage: number of executions for each line.

• Overall coverage: aggregated coverage across the package.

• Metadata: source file paths, expressions, and summary stats.

The resulting object can be printed, summarized, or passed to test.assessr::generate_test_report() to produce a human-readable test coverage report.

Returns NULL if the package cannot be installed or if the specified path does not exist.

Examples

# Example STF package included in test.assessr
pkg_source_path <- system.file(
  "test-data",
  "test.package.0001_0.1.0.tar.gz",
  package = "test.assessr"
)

# Run get_package_coverage
pkg_test_coverage <- get_package_coverage(pkg_source_path)

Read Description file and parse the package name and version

Description

Read Description file and parse the package name and version

Usage

get_pkg_desc(pkg_source_path, fields = NULL)

Arguments

Value

list with package description

get package name for display

Description

get package name for display

Usage

get_pkg_name(input_string)

Arguments

Value

pkg_disp - package name for display

Examples

pkg_source_path <- "/home/user/R/test.package.0001_0.1.0.tar.gz"
pkg_disp_1 <- get_pkg_name(pkg_source_path)
print(pkg_disp_1)

pkg <- "TxDb.Dmelanogaster.UCSC.dm3.ensGene_3.2.2.tar.gz"
pkg_disp_2 <- get_pkg_name(pkg)
print(pkg_disp_2)

Locate active test paths for Bioconductor RUnit layout

Description

Returns a *list* of one or more existing test directories suitable for normalization and use in subsequent mapping (e.g., 'get_source_test_mapping_nstf'). Designed to work with:

Usage

get_runit_test_paths(test_pkg_data, testdir)

Arguments

Details

path <- as.character(pkg_source_path) testdir <- file.path(path, "inst/unitTests") test_path_list <- find_biocgenerics_test_paths(test_pkg_data, testdir) test_path <- normalizePath( unlist(test_path_list, use.names = TRUE), winslash = "/", mustWork = FALSE )

Value

named list of **existing** directories (e.g., 'bioc_unitTests', 'tests_root'); if nothing is found, returns a single 'fallback' entry pointing to 'testdir'.

Map Bioconductor source files to test files, avoiding false positives. Tightens filename and content-based matching; handles short names like "t".

Description

Map Bioconductor source files to test files, avoiding false positives. Tightens filename and content-based matching; handles short names like "t".

Usage

get_source_test_mapping_bioc_nstf(pkg_source_path, test_dir)

Arguments

Value

data.frame with columns: source_file, test_file, evidence, has_tests

Map R Source Files to Corresponding Test Files

Description

This internal helper function scans the 'R/' and 'tests/' directories of a package and attempts to match each source file with a corresponding test file based on filename similarity.

Usage

get_source_test_mapping_nstf(pkg_source_path, test_dir)

Arguments

Value

A data frame with two columns:

source_file

Name of the source file in the 'R/' directory.

test_file

Name of the matched test file in the 'tests/' directory, or NA if no match is found.

See Also

Other nstf_utility: check_covr_skip_testit(), create_base_tests_coverage(), create_nstf_covr_list(), create_tinytest_coverage(), get_nstf_test_path(), restrict_test_paths_to_framework(), run_covr_skip_nstf()

Determine the appropriate standard test path for a package

Description

This internal utility function inspects the 'test_pkg_data' structure to identify which testing framework is used in the package and returns the corresponding test path.

Usage

get_stf_test_path(test_pkg_data, testdir)

Arguments

Value

A character string representing the path to the test directory, or 'NULL' if no known test framework is found.

Get human-readable test framework type label

Description

Get human-readable test framework type label

Usage

get_test_framework_type(test_pkg_data, framework_id)

Arguments

Value

Character. Label for test_framework_type.

Get test metadata

Description

Get test metadata

Usage

get_test_metadata(executor = NULL)

Arguments

Value

list with metadata

Summarize detailed testthat results

Description

Internal helper function to generate a long-format summary of testthat results, including status and line references.

Usage

get_tests_long_sum_stf(x)

Arguments

Value

data.frame with detailed test results including status and source line links

Safely generate skip test mapping from problem tests and test map

Description

This function filters and joins test metadata to identify which tests should be skipped based on failed or problematic test results.

Usage

get_tests_skip_stf(problem_tests, test_map)

Arguments

Value

A data frame containing the merged skip test mapping, or 'NULL' if validation or processing fails.

Helper function to replace NULL with "N/A"

Description

Helper function to replace NULL with "N/A"

Usage

handle_null(x)

Arguments

Initialise a temporary coverage environment (framework-aware)

Description

Initialise a temporary coverage environment (framework-aware)

Usage

initialise_covr_env(pkg_source_path, pkg, framework = "none", work_dir = NULL)

Arguments

Value

environment cov_env with $work_dir and $pkg_root set.

Install a Package from a Local Source Directory

Description

Attempts to install an R package from a local source directory using remotes::install_local(). The function reports on whether installation succeeded, whether the package was already installed, or whether the provided source path does not exist.

Usage

install_package_local(pkg_source_path)

Arguments

Details

The display name of the package is derived from the input path using get_pkg_name().

Value

A logical value indicating whether the package is installed after running the function.

The returned object is always of class logical:

• TRUE — The package is already installed or was successfully installed.

• FALSE — Installation failed or the path does not exist.

Output Meaning

TRUE does not necessarily imply that the installation occurred during this function call—it may also mean the package was already installed.

FALSE indicates a failure to install or an invalid path. All diagnostic messages are printed via message() for user visibility.

Examples

## Not run: 
results <- install_package_local("pkg_source_path")
print(results)

## End(Not run)

Detect if a package uses the Bioconductor RUnit layout

Description

Heuristics: - inst/unitTests exists, OR - tests/run_unitTests.R exists, OR - explicit flag in test_pkg_data$has_BioG_test

Usage

is_bioc_runit_layout(pkg_source_path, test_pkg_data = NULL)

Detect if a package uses RUnit layout (BioC or RUnit-only)

Description

Returns TRUE when the package has RUnit tests in inst/unitTests (with or without the BiocGenerics .test() runner). Heuristics: - test_pkg_data$has_BioG_test (BioC full layout), OR - test_pkg_data$has_RUnit_test (inst/unitTests, no .test required), OR - inst/unitTests exists, OR - tests/run_unitTests.R exists

Usage

is_runit_layout(pkg_source_path, test_pkg_data = NULL)

Arguments

Value

Logical. TRUE if the package uses RUnit layout.

Load Base R packages into an isolated coverage environment

Description

Populate an isolated environment (typically created with 'new.env(parent = baseenv())') with objects needed to mimic the standard Base R package surface during coverage or test evaluation.

Usage

load_base_r_packages_into_env(env, overwrite = FALSE)

Arguments

Details

The 'base' package itself is already available via 'baseenv()' and is therefore not copied into 'env'. The function instead:

- loads datasets from the 'datasets' package into 'env', and - copies exported objects from other Base R packages into 'env' (e.g. 'stats', 'utils', 'graphics', 'grDevices', 'methods', etc.).

This is useful when tests are evaluated in a deliberately isolated environment whose parent is 'baseenv()', because objects from packages such as 'stats' (e.g. 'rnorm') and 'datasets' (e.g. 'mtcars', 'iris') are not automatically visible there.

The Base R package set handled here is:

• 'base'

• 'compiler'

• 'datasets'

• 'graphics'

• 'grDevices'

• 'grid'

• 'methods'

• 'parallel'

• 'splines'

• 'stats'

• 'stats4'

• 'tcltk'

• 'tools'

• 'utils'

Because 'base' is already reachable through 'baseenv()', it is excluded from the explicit copy step.

Value

A named list with two character vectors:

exports_loaded

Exported objects copied from Base R packages other than 'base' and 'datasets'.

datasets_loaded

Dataset objects loaded from the 'datasets' package.

Load and Install Package Dependencies from a DESCRIPTION File

Description

Reads a package's 'DESCRIPTION' file, parses dependency fields ('Depends', 'Imports', 'Suggests'), installs missing packages or those that do not satisfy version constraints, loads namespaces, and—for packages listed under **Depends**—imports their exported symbols into a provided evaluation environment. This makes bare function names visible when evaluating code in environments that do not inherit from '.GlobalEnv' (e.g., environments with 'baseenv()' as parent).

Usage

load_dependencies_into_env(pkg_source_path, env)

Arguments

Details

This function avoids calling 'installed.packages()' because that function scans all installed packages and is slow on some platforms (especially Windows and network filesystems). Using 'requireNamespace()' is the recommended approach for checking whether a package is installed and usable. 'packageDescription()' is used only on a small set of packages when version information or priority metadata is needed.

When evaluating code in environments that do not inherit from '.GlobalEnv', attaching packages does not necessarily make their exported symbols available. For this reason, exports from packages listed under 'Depends' are explicitly imported into the target environment.

Value

Invisibly returns 'TRUE' on success.

Behavior

1. **Dependency parsing** Parses entries of the form '"pkg"' or '"pkg (op version)"', where the operator 'op' is one of '>=', '>', '<=', '<', '=='. HTML-escaped forms ('&gt;', '&lt;') are normalized.

2. **Dependency fields** Dependencies are extracted from the 'Depends', 'Imports', and 'Suggests' fields. The 'Depends: R (>= x.y.z)' entry is ignored for installation purposes, but the R version constraint is validated.

3. **Base/recommended packages** Unlike tools such as 'R CMD check', this function **does not skip** recommended or base packages (e.g., 'graphics', 'stats', 'utils', 'grDevices') because packages listed in 'Depends:' must be made visible in the target evaluation environment even when its parent is 'baseenv()'. If a package is already installed with R, no installation is attempted.

4. **Availability and version checks** Package presence is determined via 'requireNamespace(pkg, quietly = TRUE)' instead of 'installed.packages()', for performance and portability. If a version constraint is declared, the installed version (from 'packageDescription(pkg, fields = "Version")') is compared using 'utils::compareVersion()'.

5. **Package installation** - For constraints of the form '>=' or '>': 'install.packages()' is used (latest version is assumed valid). - For '<=', '<', or '==': 'remotes::install_version()' is used to install an exact version.

6. **Loading behavior** Each dependency is namespace-loaded via 'loadNamespace()'. Packages that appear in the 'Depends' field have all their **exported symbols imported** into the supplied 'env'. This makes calls such as 'plot()', 'lm()', or 'head()' resolve correctly inside environments whose parent is not '.GlobalEnv'.

Load Datasets from a Package

Description

Loads all datasets from a specified installed package into the cov environment. It first attempts to load ‘.rda' files from the package’s 'data/' directory. If none are found, it falls back to using 'data()' to load datasets listed in the package metadata.

Usage

load_package_datasets(pkg_names, env, source_paths = NULL, overwrite = FALSE)

Arguments

Details

This function is intended for internal use. It silently attempts to load each dataset and suppresses errors if loading fails. Datasets are loaded into the cov environment.

Value

A character vector of dataset names that were attempted to be loaded. Returns 'NULL' if the package is not installed.

Load exported objects from installed packages into an environment

Description

Copy exported objects (typically functions, but also exported constants or other objects) from one or more installed package namespaces into a target environment.

Usage

load_package_exports_into_env(pkg_names, env, overwrite = FALSE)

Arguments

Details

This is useful when evaluating code in an isolated environment, such as one created with 'new.env(parent = baseenv())', where package exports that are normally available on the search path (for example from 'stats' or 'utils') are not automatically visible.

The function does not attach packages to the search path. Instead, it copies exported objects directly into 'env'.

For each package in 'pkg_names', this function:

1. checks whether the package namespace is available,

2. retrieves the package's exported names,

3. obtains each exported object with 'getExportedValue()',

4. assigns the object into 'env'.

Packages that are not installed or cannot be loaded are skipped with a message.

Value

A character vector of fully qualified object names that were loaded, in the form '"pkg::name"'.

Load package objects into a coverage environment

Description

This internal function loads all objects from a package namespace into a specified environment. It is used by 'create_covr_list_no_skip()' to prepare the environment for coverage analysis.

Usage

load_package_into_env(pkg_source_path, pkg, cov_env)

Arguments

Value

Invisibly returns TRUE if successful, otherwise stops with an error.

Load Testthat Helper Files into Environment

Description

This function searches for all files in the 'tests/testthat' directory that match the pattern 'helper-*.R' and sources them into the provided environment. This is useful when running coverage with 'covr::environment_coverage()' to ensure helper functions are available during test execution.

Usage

load_test_helpers(env, helper_dir = "tests/testthat")

Arguments

Value

Invisibly returns 'TRUE' if all files are sourced successfully.

Map the Structure of Expectations in a Testthat File

Description

This function parses a single testthat test file and extracts a structured representation of the expectations it contains. It identifies top‑level test blocks (e.g., 'test_that()', 'describe()', 'tar_test()') and any nested expectation blocks (e.g., 'it()'). The result maps expectation location, context, and source line ranges for downstream analysis.

Usage

map_test(path)

Arguments

Details

The function uses 'utils::getParseData()' to inspect parse information from the test file and constructs a hierarchical mapping of:

• test block context (e.g., 'describe()', 'test_that()')

• test labels or sub‑contexts (e.g., 'it()' blocks)

• expectation type

• source line ranges associated with each expectation

If the file does not contain any parseable test blocks or expectations, 'NULL' is returned.

Value

A 'data.frame' in which each row corresponds to an expectation identified in the test file. Typical columns include:

description

Context or test block label derived from the test file.

expectation

The expectation type (e.g., 'expect_equal').

linerange

Numeric vector giving the range of lines associated with the expectation.

test

Test label (combined description and nested block label, if applicable).

This structured output is used internally by STF test‑mapping functions (e.g., 'map_tests_stf()') for coverage analysis, skip mapping, and test reporting.

See Also

getParseData

Other stf_utility: create_coverage_skip_stf(), map_tests_stf(), nest_test(), run_covr_skip_stf()

Map the Structure of Testthat Tests (Standard Testing Framework)

Description

This function analyses the test directory used by the Standard Testing Framework (STF), typically 'tests/testthat/', and extracts a structured representation of the unit tests contained in the directory. It identifies test files, expectations, contexts, test names, and associated line ranges.

Usage

map_tests_stf(path = "tests/testthat")

Arguments

Details

The function scans all testthat test files matching the pattern 'test*.R'. For each file, it extracts structured metadata describing the hierarchy of expectations, including:

• file name

• context or description

• test label

• expectation type

• line ranges associated with each expectation

Files that contain no parseable test structure are omitted. If no valid test files are found, the function returns 'NULL'.

Value

A consolidated 'data.frame' where each row corresponds to an expectation discovered within the STF test directory. The data frame typically contains:

file

Name of the test file in which the expectation appears.

test

The combined description and test label assigned to the expectation.

expectation

The expectation type detected (e.g., 'expect_equal').

linerange

The associated line numbers for that expectation.

This structured mapping is used by downstream STF processing functions to support skip mapping, coverage enhancement, and reporting.

See Also

list.files, lapply, rbind

Other stf_utility: create_coverage_skip_stf(), map_test(), nest_test(), run_covr_skip_stf()

Extract and Structure Expectations from Parsed Test Blocks

Description

This internal helper takes a list of parsed test blocks (as produced by nest_test()) and extracts expectation calls from each block using get_expect(). It then assembles all detected expectations into a structured data frame that associates each expectation with its corresponding test label.

Usage

nest_expect(x)

Arguments

Details

For each block in x, the function:

• calls get_expect() to extract expectation function calls and their line ranges,

• removes blocks with no expectations,

• attaches a test label using the block's list name, and

• binds all expectation results into a single consolidated data frame.

If no expectations are found in any block, the function returns NULL.

Value

A data.frame in which each row corresponds to an expectation extracted from the supplied test blocks. Typical columns include:

expectation

Name of the expectation function (e.g., "expect_equal").

line1

Starting line number of the expectation expression.

line2

Ending line number of the expectation expression.

test

Label identifying the test block the expectation belongs to.

Returns NULL if no expectations are detected.

Group Parsed Testthat Code into Logical Test Blocks (Internal)

Description

This internal helper groups parse data from a testthat test file into logical test blocks based on calls to block‑defining functions such as 'context()', 'test_that()', 'describe()', 'it()', or 'tar_test()'. It identifies top‑level expressions that match a given function‑name regex and returns a named list of data frames—one per detected block—trimmed to the relevant code region.

Usage

nest_test(x, token_text = "^context$")

Arguments

Details

The function locates top‑level expressions whose function call tokens (SYMBOL_FUNCTION_CALL) match token_text. For each matching block, it:

• assigns a human‑readable name using the function name and its string constant argument (when available),

• trims the block to exclude leading parse noise, and

• returns the subset of x corresponding to that block.

Block names are prefixed with the function (e.g., "test_that: ...", "describe: ...", "it: ...", "tar_test: ...") when the function is recognized.

Value

A named list of data frames, where each element represents the parse rows for a single detected test block. Names encode the block function and label. If no matching blocks are found, an empty list is returned. This structure is consumed by higher‑level STF mapping helpers (e.g., map_test(), map_tests_stf()) to derive expectations, contexts, and line ranges.

See Also

getParseData, map_test, map_tests_stf

Other stf_utility: create_coverage_skip_stf(), map_test(), map_tests_stf(), run_covr_skip_stf()

Normalize test results for single or multi-framework structure

Description

For single-framework results, passes through unchanged. For multi-framework, sets multi_framework and frameworks while keeping results as a named list of per-framework blocks (no flattening).

Usage

normalize_test_results(test_results)

Arguments

Value

A list with multi_framework (logical), frameworks (character, multi only), and results preserved for multi-framework.

Prepare a BioC/RUnit package for testing Detaches common BioC infrastructure packages (if attached) and load_all() the target package before RUnit tests. Also clears R_TESTS to avoid interference from the check harness.

Description

Prepare a BioC/RUnit package for testing Detaches common BioC infrastructure packages (if attached) and load_all() the target package before RUnit tests. Also clears R_TESTS to avoid interference from the check harness.

Usage

prepare_for_bioc_runit(pkg_name, pkg_source_path, detach_bioc_infra)

Arguments

Prepare package-specific test environment for data.table (internal)

Description

For data.table, Only "mirror" mode is supported here: copy inst/tests/* -> tests/ and clean up.

Usage

prepare_tests_for_package_dt(
  pkg_name,
  pkg_source_path,
  test_files,
  mode = c("mirror")
)

Details

Returns a list with: - test_files: character() of wrapper files to execute - teardown: function() to revert any changes (delete mirrored files, unset env)

Remove New Globals from Environment Based on Initial Snapshot

Description

This function removes objects from an environment that were added after a recorded initial state. Optionally filters by pattern.

Usage

remove_new_globals(env, initial_state, patterns = NULL, dry_run = FALSE)

Arguments

Value

Invisibly returns a character vector of removed object names.

Remove mapping rows that point to run_unitTests.R

Description

Remove mapping rows that point to run_unitTests.R

Remove mapping rows that point to run_unitTests.R

Usage

remove_run_unitTests_mapping(mapping, test_pkg_data)

remove_run_unitTests_mapping(mapping, test_pkg_data)

Arguments

Value

The filtered mapping data.frame with run_unitTests.R rows removed.

The filtered mapping data.frame with run_unitTests.R rows removed.

Restrict a list of test paths to a single framework

Description

Filters a named list of candidate test directories (typically produced by get_nstf_test_path()) down to the entry that corresponds to a requested framework. If no usable mapping can be made, the input list is returned unchanged.

Usage

restrict_test_paths_to_framework(test_path_list, framework)

Arguments

Details

The function maps framework to a primary key in test_path_list as follows:

• "testthat" → "testthat"

• "testit" → "testit" (falls back to "nonstandard_testit_root" if "testit" is NULL)

• "tests_base" → "base_tests_root"

• "tinytest" → "tinytest"

For framework == "testit", if test_path_list[["testit"]] is NULL and test_path_list[["nonstandard_testit_root"]] is present, the latter is used instead. No directories are created or validated here; the function only selects from the provided list.

Value

list. Either:

• a single-element named list containing only the resolved framework path (name is the selected key), or

• the original test_path_list if framework is NULL/empty, maps to an unknown key, or the resolved key is absent in test_path_list.

See Also

get_nstf_test_path

Other nstf_utility: check_covr_skip_testit(), create_base_tests_coverage(), create_nstf_covr_list(), create_tinytest_coverage(), get_nstf_test_path(), get_source_test_mapping_nstf(), run_covr_skip_nstf()

Run Coverage and Return Structured Coverage Results

Description

This function executes code coverage analysis for a package using the 'covr' framework. It is typically used after a package has been installed locally and test files are available. The function runs coverage in an isolated process (using 'callr') and returns a structured summary of overall and file‑level coverage.

Usage

run_coverage(pkg_source_path, timeout = Inf)

Arguments

Details

The function invokes covr’s coverage evaluation in a clean R session and extracts both:

• total coverage: percentage of lines covered across the package, and

• function/file‑level coverage: coverage data for individual files.

It is used internally by higher‑level functions such as run_covr_modes() and skip‑aware coverage wrappers in the Standard Testing Framework (STF).

Value

A named list containing:

total_cov

Numeric. Aggregated coverage percentage for the package.

res_cov

A list containing file‑level or function‑level coverage results as returned by 'covr'. This includes per‑file coverage, errors, and diagnostic notes if present.

Returns NULL if coverage could not be computed.

Examples

# Save and adjust CRAN mirror for reproducibility
r <- getOption("repos")
old <- options(repos = r)
r["CRAN"] <- "http://cran.us.r-project.org"
options(repos = r)

# Example package from test.assessr
dp <- system.file(
  "test-data",
  "test.package.0001_0.1.0.tar.gz",
  package = "test.assessr"
)

# Set up package source directory
install_list <- set_up_pkg(dp)
pkg_source_path <- install_list$pkg_source_path

# Install locally to enable testing and coverage
package_installed <- install_package_local(pkg_source_path)

if (isTRUE(package_installed)) {
  coverage_results <- run_coverage(pkg_source_path)
}

# Restore user's original repository settings
options(old)

Run covr in a Subprocess with a Timeout

Description

This internal helper runs coverage evaluation in a separate R subprocess using 'callr'. It allows coverage to be computed with a specified timeout, ensuring that long‑running or hanging test processes do not block further analysis.

Usage

run_covr(path, timeout)

Arguments

Details

The function launches a safe R session via callr::r_safe() and executes the relevant covr routines within that isolated environment. This is used internally by higher‑level STF/NSTF coverage functions to ensure reproducible and controlled coverage execution.

Value

A coverage object returned by the underlying covr call, or NULL if the subprocess execution fails or times out.

Run Coverage Analysis with Test Detection

Description

This function inspects the test configuration of an R package and runs code coverage analysis using any available testing framework, including 'testthat', 'testit', base R test scripts, or Bioconductor-style tests. If no recognised testing configuration is found, a default zero‑coverage result is returned.

Usage

run_covr_modes(pkg_source_path, covr_timeout = 60)

Arguments

Value

A named list containing coverage results, package metadata, and test configuration details. The returned list includes (but is not limited to):

pkg_name

Character. Package name extracted from the DESCRIPTION file.

pkg_ver

Character. Package version.

date_time

Timestamp of when the analysis was run.

executor

User or environment running the analysis.

sysname, version, release, machine

System metadata.

r_version

R version used during analysis.

test_framework_type

Character. Detected testing framework type.

covr_list

A nested list containing:

total_cov

Numeric. Aggregated coverage percentage.

res_cov

File‑level and line‑level coverage details.

errors, notes

Any warnings or notes detected during testing.

test_pkg_data

A list describing the test configuration of the package (presence of testthat, testit, base tests, snapshots, etc.).

This function always returns a value. When no supported testing framework is detected, a default object with zero coverage and diagnostic information is returned.

Examples

dp <- system.file("test-data", 
  "test.package.0001_0.1.0.tar.gz", 
  package = "test.assessr")

# set up package
install_list <- set_up_pkg(dp)

package_installed <- install_list$package_installed
pkg_source_path <- install_list$pkg_source_path

# install package locally to ensure test works
package_installed <- install_package_local(pkg_source_path)
package_installed <- TRUE

covr_mode_list <- run_covr_modes(pkg_source_path)

Run coverage with skip detection for Bioconductor RUnit-based packages

Description

'run_covr_skip_bioc_nstf()' orchestrates coverage for packages using the Bioconductor **RUnit** layout, such as **BiocGenerics** and packages that store tests in 'inst/unitTests' or ship a 'tests/run_unitTests.R' wrapper.

Usage

run_covr_skip_bioc_nstf(
  pkg_source_path,
  test_pkg_data,
  cov_env,
  framework = NULL
)

Arguments

Details

The function: 1. Builds a source-to-test mapping (using your existing 'get_source_test_mapping_nstf()'). 2. Removes any 'run_unitTests.R' wrapper from the mapping (via 'remove_run_unitTests_mapping()'). 3. Prepares a development environment **before** running RUnit tests: - Detaches commonly attached BioC infrastructure packages ('IRanges', 'S4Vectors', 'BiocGenerics') to avoid namespace/shim conflicts. - Calls 'pkgload::load_all()' to load the package under test. - Clears 'R_TESTS' to avoid R CMD check harness interference when running RUnit programmatically. 4. Identifies problem/skip-able tests via your RUnit-aware 'check_covr_skip_nstf()' (which should use 'RUnit::runTestFile()' + 'RUnit::getErrors()' per file). 5. Builds a list of test files **under 'inst/unitTests'** excluding any that should be skipped. 6. Exposes namespace objects + datasets to a dedicated environment and runs coverage with 'covr::environment_coverage()'.

Use this function **only** for packages that follow the Bioconductor RUnit layout: - tests are located in 'inst/unitTests/', and/or - a 'tests/run_unitTests.R' wrapper exists that calls an internal '.test()' / 'testPackage()' runner.

Value

A 'covr' coverage object on success; 'NULL' on failure (via 'cleanup_and_return_null()').

A covr coverage object, or NULL on failure.

Run Coverage Analysis on data.table Package Source and Tests

Description

This function maps source files to test files, checks for skipped/problematic tests, runs the remaining test files manually, calculates coverage, and optionally generates a report.

Usage

run_covr_skip_dt_nstf(pkg_source_path, test_pkg_data, cov_env)

Arguments

Value

returns a list with coverage object and source files with no tests.

Run Coverage Analysis on Package Source and Non‑Standard Tests (NSTF)

Description

This function maps package source files to non‑standard test scripts, detects failing or skipped tests, executes the remaining tests manually, computes code coverage, and returns structured results. It is intended for packages that do not use the standard 'testthat' framework (e.g., base R tests under 'tests/', Bioconductor‑style tests in 'inst/tests/', or other legacy/custom scripts).

Usage

run_covr_skip_nstf(pkg_source_path, test_pkg_data, cov_env, framework = NULL)

Arguments

Details

This NSTF workflow does not rely on 'testthat' reporters. Instead, it:

• maps source files to available NSTF test scripts,

• identifies failing or problematic tests and derives a skip map,

• runs the remaining test scripts, and

• computes coverage on the successfully executed regions.

The output mirrors the structure returned by the STF skip‑aware workflow so that downstream reporting remains consistent across frameworks.

Value

A named list containing coverage results and diagnostics:

total_cov

Numeric. Overall percentage of lines covered across the package.

res_cov

List. File‑ or element‑level coverage results (as derived from covr output), including per‑file coverage, any errors, and diagnostic notes.

long_summary

Long‑format summary of test outcomes (e.g., PASS/FAIL/ERROR/SKIPPED), when available from the NSTF execution.

test_skip

A data frame describing lines or regions skipped during coverage (if any). NULL if no skipping was required.

untested_sources

Character vector of source files for which no tests were found.

If no valid NSTF test directory is detected, an “empty” coverage object may be returned via create_empty_covr_list().

See Also

Other nstf_utility: check_covr_skip_testit(), create_base_tests_coverage(), create_nstf_covr_list(), create_tinytest_coverage(), get_nstf_test_path(), get_source_test_mapping_nstf(), restrict_test_paths_to_framework()

Run coverage with skip detection for RUnit and Bioconductor RUnit-based packages

Description

'run_covr_skip_runit_nstf()' orchestrates coverage for packages using the Bioconductor **RUnit** layout, such as **BiocGenerics** and packages that store tests in 'inst/unitTests' or ship a 'tests/run_unitTests.R' wrapper.

Usage

run_covr_skip_runit_nstf(
  pkg_source_path,
  test_pkg_data,
  cov_env,
  framework = NULL
)

Arguments

Details

The function: 1. Builds a source-to-test mapping (using your existing 'get_source_test_mapping_nstf()'). 2. Removes any 'run_unitTests.R' wrapper from the mapping (via 'remove_run_unitTests_mapping()'). 3. Prepares a development environment **before** running RUnit tests: - Detaches commonly attached BioC infrastructure packages ('IRanges', 'S4Vectors', 'BiocGenerics') to avoid namespace/shim conflicts. - Calls 'pkgload::load_all()' to load the package under test. - Clears 'R_TESTS' to avoid R CMD check harness interference when running RUnit programmatically. 4. Identifies problem/skip-able tests via your RUnit-aware 'check_covr_skip_nstf()' (which should use 'RUnit::runTestFile()' + 'RUnit::getErrors()' per file). 5. Builds a list of test files **under 'inst/unitTests'** excluding any that should be skipped. 6. Runs coverage with 'covr::environment_coverage()': tries 'tests/doRUnit.R' first when present (matches R CMD check for CRAN RUnit packages); falls back to a custom runner that calls 'RUnit::runTestFile()' on each test file if doRUnit.R fails or is absent.

Use this function **only** for packages that follow the Bioconductor RUnit layout: - tests are located in 'inst/unitTests/', and/or - a 'tests/run_unitTests.R' wrapper exists that calls an internal '.test()' / 'testPackage()' runner.

Value

A 'covr' coverage object on success; 'NULL' on failure (via 'cleanup_and_return_null()').

A covr coverage object, or NULL on failure.

Run Coverage with Skipped Failing Tests (Standard Testing Framework)

Description

This function runs testthat-based test execution and code coverage while identifying and skipping failing tests. It is designed for use with standard testing frameworks (STF), primarily 'testthat', and supports automated skip mapping to enable coverage calculation even when some tests fail.

Usage

run_covr_skip_stf(pkg_source_path, test_pkg_data, cov_env)

Arguments

Details

The function:

• executes tests and collects detailed test results,

• identifies failing, erroring, or skipped tests,

• constructs skip maps to temporarily comment out failing test lines,

• computes coverage on the remaining tests, and

• returns a combined object containing coverage and test summaries.

Value

A named list containing coverage results and test diagnostics. The structure includes:

total_cov

Numeric. Overall coverage percentage.

res_cov

A nested list with file-level coverage, errors, and notes.

long_summary

Long-format test results including PASS/FAIL/ERROR/SKIPPED.

test_skip

A data frame describing test lines skipped during coverage, if applicable.

If no tests fail, the returned list describes full coverage based on unskipped tests. If no valid STF test directory is found, an empty coverage object is returned via create_empty_covr_list().

See Also

Other stf_utility: create_coverage_skip_stf(), map_test(), map_tests_stf(), nest_test()

Run coverage for a single test framework

Description

Run coverage for a single test framework

Usage

run_one_framework(framework, pkg, test_pkg_data, pkg_source_path, covr_timeout)

Arguments

Value

List with total_cov, res_cov, test_framework_type, framework_id.

Safely perform a left join with error handling

Description

This helper function attempts to join two data frames using 'dplyr::left_join()'. If an error occurs during the join (for example, due to missing columns or incompatible types), the function issues a warning and returns 'NULL' instead of stopping execution.

Usage

safe_left_join(x, y, by, relationship = "many-to-many", ...)

Arguments

Value

A data frame resulting from the left join if successful, otherwise 'NULL' when an error occurs.

Safely unload a package to avoid coverage conflicts

Description

This internal function attempts to unload a specified package if it is currently loaded. It is used to prevent coverage conflicts when reloading the package in a custom environment.

Usage

safe_unload_package(pkg)

Arguments

Value

NULL (invisibly). Messages are printed to indicate success or failure.

Helper to conditionally apply handle_null or abbreviation

Description

Helper to conditionally apply handle_null or abbreviation

Usage

safe_value(x)

Arguments

Create Information on Local Package Installation

Description

This function unpacks a package tarball using unpack_tarball() and returns information about whether the unpacked directory exists. It is a lightweight preparatory step used before attempting a local package installation.

Usage

set_up_pkg(dp)

Arguments

Value

A named list with the following elements:

• package_installed — Logical. TRUE if the unpacked package directory exists, otherwise FALSE.

• pkg_source_path — Character string giving the unpacked package source directory, or "" if unpacking failed.

The returned object is always a base R list. It contains no side effects besides calling unpack_tarball() and checking filesystem paths.

Output Meaning

A value of package_installed = TRUE indicates that the unpacked directory exists on disk and can be used for local installation.

package_installed = FALSE indicates either:

• unpack_tarball() returned an empty result, or

• the unpacked directory does not exist on disk.

Examples

## Not run: 
set_up_pkg(path/to/package, "mypackage")

## End(Not run)

Set up a coverage environment for isolated test execution

Description

Prepare an existing coverage environment for use with coverage workflows that evaluate tests in an isolated environment, typically one created with 'new.env(parent = baseenv())'.

Usage

setup_covr_env(
  pkg_source_path,
  pkg_name,
  test_path = "tests/testthat",
  cov_env
)

Arguments

Details

The setup process:

- loads helper files from 'tests/testthat', - loads package namespace objects into 'cov_env', - resolves the project root, - loads package datasets into 'cov_env', - loads Base R datasets and exports into 'cov_env', - optionally loads 'nycflights13' datasets if available, - loads dependencies into 'cov_env', and - unloads the package namespace afterward to reduce conflicts.

This function does **not** create 'cov_env'; it expects an existing environment to be supplied.

This function is designed for workflows where 'cov_env' is deliberately isolated (for example with 'parent = baseenv()'). In such cases, objects from packages like 'stats' and 'datasets' are not automatically visible, so they are explicitly loaded into 'cov_env'.

The package 'nycflights13' is treated as optional: if it is installed, its datasets are loaded into 'cov_env'; otherwise it is silently skipped.

Value

A named list with components:

cov_env

The populated coverage environment.

datasets_loaded

Character vector of dataset objects loaded into 'cov_env' from the target package, 'datasets', and optionally 'nycflights13'.

base_r_datasets_loaded

Character vector of datasets loaded from the 'datasets' package.

base_r_exports_loaded

Character vector of exported objects copied from Base R packages other than 'base' and 'datasets'.

root_dir

Resolved project root path.

initial_state

Character vector of object names present in 'cov_env' before setup.

helpers_loaded

Character vector of helper files successfully sourced into 'cov_env'.

Untar package and return installation directory

Description

Untar package and return installation directory

Usage

unpack_tarball(pkg_tar, temp_file_name = "temp_file_")

Arguments

Add Identifier Column and Remove Row Names from a Data Frame

Description

This internal helper restructures a data frame by adding an identifier column (e.g., file name or test label) and removing row names. It is used by STF parsing functions to attach contextual labels (such as test block names or file names) to expectation or test‑block structures.

Usage

unrowname(identifier, ret, label)

Arguments

Details

The function:

• extracts the data frame corresponding to identifier,

• appends a new column containing the identifier value,

• removes row names for clean downstream processing, and

• reorders columns so the identifier appears first.

This structure is used by STF mapping helpers such as nest_expect() and map_tests_stf() to carry forward file or test labels when constructing unified test‑mapping tables.

Value

A data.frame with an identifier column prepended and row names removed. The remaining columns retain their original structure.