Title:	Assessing Package Test Reliability and Quality
Version:	1.1.1
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, testthat (≥ 3.0.0), tidyr, utils, withr
Suggests:	devtools, DT, here, kableExtra, 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-02-24 10:54:56 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-03-02 22:20: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-testthat)

Description

This internal utility runs test files mapped to source files and identifies any that produce warnings or errors when sourced. This helper does **not** evaluate tests written using 'testthat'; it is intended for legacy or lightweight “non-testthat” test files.

Usage

check_covr_skip_nstf(pkg_source_path, mapping)

Arguments

Details

The function sources each test file in a clean environment and captures whether sourcing resulted in a warning or an error. Files that produce no issues are omitted from the output.

Value

A data frame with the following columns:

* **test_file** — The name of the test file that produced a diagnostic * **issue_type** — One of: * '"warning"' — sourcing the file triggered a warning * '"error"' — sourcing the file threw an error * '"No tests skipped"' — returned when no problems are detected

The returned object is always a base R 'data.frame'. If no warnings or errors occur in any sourced test file, the function returns a single-row data frame indicating '"No tests skipped"'.

Output Meaning

The output is intended to help developers identify test files that fail to run cleanly **before** test execution, ensuring they do not silently skip or break coverage workflows.

See Also

Other nstf_utility: check_covr_skip_testit(), get_nstf_test_path(), get_source_test_mapping_nstf(), run_covr_skip_nstf()

Run testit Tests Individually and Capture Issues

Description

This internal NSTF utility runs 'testit' test files one-by-one and reports whether sourcing each file produces a warning or an error. The function uses dynamic package-root detection by searching upward for a 'DESCRIPTION' file to ensure tests run in the correct working directory.

Usage

check_covr_skip_testit(pkg_name, mapping, test_path)

Arguments

Details

The function does not evaluate testthat-based tests and is intended only for lightweight or legacy 'testit' scripts.

Value

A base R 'data.frame' with two columns:

* **test_file** — The name of the testit file evaluated * **issue_type** — One of: * '"warning: <message>"' — A warning was raised while sourcing the file * '"error: <message>"' — An error occurred while sourcing the file * '"No tests skipped"' — Returned as a single-row result if no warnings or errors occurred in any test file

The data frame summarizes which testit files fail to run cleanly, allowing early detection of broken or skipped tests in NSTF workflows.

Output Meaning

The returned data frame indicates potential problems with testit files before coverage or build steps occur. There is no side effect other than evaluation of test files; all results are reported in the data frame.

See Also

Other nstf_utility: check_covr_skip_nstf(), get_nstf_test_path(), get_source_test_mapping_nstf(), 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.

Usage

check_elements_simple(x, elems)

Arguments

Value

A list with:

present

Character vector of elements that exist in the list.

missing

Character vector of elements that do not exist in the list.

Check for Testing Infrastructure and Snapshot Files

Description

This function inspects an R package source tree and detects the presence of common testing frameworks ('testthat', 'testit', base R tests, BioGenerics/Bioconductor-style tests) as well as snapshot files used for golden testing.

Usage

check_pkg_tests_and_snaps(pkg_source_path)

Arguments

Value

A list containing logical indicators and file counts describing the test configuration of the package. The list includes:

has_testthat

Logical. Whether 'tests/testthat/' exists.

has_testit

Logical. Whether 'tests/testit/' exists.

has_tests_base

Logical. Whether base R test files exist in 'tests/'.

has_BioG_test

Logical. Whether BioGenerics-style tests exist in 'inst/tests/'.

bioc_unit_tests_dir

Character. Path to BioGenerics unit test directory (if any).

bioc_run_ut_path

Character. Path to BioGenerics 'run_unitTests.R' (if any).

has_snaps

Logical. Whether '_snaps/' exists inside 'tests/testthat/'.

n_golden_tests

Integer. Number of snapshot test files inside '_snaps/'.

n_test_files

Integer. Number of 'test-*.R' files in 'tests/testthat/'.

This function always returns a value. It does **not** perform side effects other than reading the package directory structure.

Examples

# Adjust CRAN repo (example only)
r <- getOption("repos")
r["CRAN"] <- "http://cran.us.r-project.org"
old <- options(repos = r)

# Example package contained in test.assessr
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)
pkg_source_path <- install_list$pkg_source_path

# Install package locally (ensures correct test paths)
install_package_local(pkg_source_path)

# Detect tests and snapshots
test_pkg_data <- check_pkg_tests_and_snaps(pkg_source_path)

# Restore options
options(old)

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 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)

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)

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 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)

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

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)

Extract the Last Two Path Components from a File Path

Description

This helper function takes any full file path and extracts only the last two components, such as '"R/add.R"'. It supports both forward slashes ('/') and backslashes ('\') to accommodate Windows, macOS, and Linux paths.

Usage

extract_short_path(long_file_name)

Arguments

Details

Trailing separators are preserved where meaningful (e.g., '"R/"' when the input ends with a slash). Empty path components are removed except when required to detect a trailing separator.

Value

A character scalar containing the last two components of the path joined with a forward slash—for example '"R/add.R"'—or a single component if only one exists. The returned value is always of class character.

Output Meaning

This function is intended for display and logging purposes, where only the tail portion of a full file path is meaningful. It does not check for file existence; it simply processes the string supplied by the user.

Examples

extract_short_path("pkg/R/add.R")
extract_short_path("C:\\\\projects\\\\mypkg\\\\R\\\\helper.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

Ensure Test Results Have Valid Context Labels

Description

This function normalizes the 'context' field in testthat test results. Some test result objects may have missing, empty, or 'NA' context values. This helper function assigns a meaningful context by using the associated file name (excluding the '.R' extension) whenever the original context is unavailable.

Usage

fix_test_context(test_results)

Arguments

Value

A list of test result objects where all entries have a non-empty 'context' value. If a test result originally lacked a valid context, its context is replaced by the corresponding test file name. The structure of each test result object is otherwise unchanged.

This output is used by downstream functions that rely on context labels for grouping, mapping, or summarizing test outcomes.

Generate Coverage Section

Description

Generates the Coverage section for the HTML report.

Usage

generate_coverage_section(assessment_results, pkg_name)

Arguments

Generate Test Details

Description

Generates the Test Details table for the HTML report.

Usage

generate_test_details(assessment_results)

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

This internal NSTF utility detects and returns all relevant test directories used by an R package. It combines declared test framework flags in test_pkg_data with filesystem-based detection for robustness.

Usage

get_nstf_test_path(test_pkg_data, testdir)

Arguments

Details

Supported directory layouts include:

• testthat: tests/testthat/

• 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/

If no test directory of any supported type is detected, the output falls back to a single entry: default_tests_root = <tests/>.

Value

list. A named list of character vectors giving all detected applicable test directories. Possible names include:

• testthat – path to tests/testthat/

• testit – path to tests/testit/

• nonstandard_testit_root – tests/ when both test-ci/ and test-cran/ exist

• base_tests_root – tests/ if *.R files exist directly

• bioc_unitTests – path to inst/unitTests/

• default_tests_root – fallback tests/ directory

Output Meaning

The returned list describes all test frameworks detected in a package. Each element is a filesystem path that the NSTF workflow should consider when identifying or running tests. Duplicate paths (e.g., multiple roles pointing to tests/) are automatically removed.

See Also

Other nstf_utility: check_covr_skip_nstf(), check_covr_skip_testit(), get_source_test_mapping_nstf(), 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
get_package_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

Extracts a display-friendly package name from either a file path or a filename. The function removes directory components (if present) and then returns the substring up to the first underscore or hyphen. This is useful for converting paths or tarball names into a clean package identifier.

Usage

get_pkg_name(input_string)

Arguments

Value

A character scalar containing the cleaned package name.

The returned object is always of class character and corresponds to the portion of the filename before the first underscore or hyphen.

Output Meaning

The value represents a human‑readable package name extracted from a file path or filename. It does not validate whether the extracted name corresponds to an installed or existing package—only that it conforms to the expected tarball naming convention.

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)

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 NSTF utility scans the package's 'R/' directory and the specified test directory and attempts to match each source file with a corresponding test file. Matching is based on filename similarity between source files and test files (case-insensitive, substring matching).

Usage

get_source_test_mapping_nstf(pkg_source_path, test_dir)

Arguments

Details

The function is intended for lightweight structural checks in NSTF workflows and does not interpret test contents.

Value

A base R 'data.frame' containing two columns:

* **source_file** — Name of the '.R' file found in the 'R/' directory * **test_file** — Name of the matched test file from 'test_dir', or 'NA' if no matching file is found

The mapping shows which source files have corresponding tests and which do not, enabling automated checks for test completeness in NSTF pipelines.

Output Meaning

A row with 'test_file = NA' indicates that no test file appears to match the given source file. The returned data frame is solely a structural mapping; no tests are run, and no side effects occur.

See Also

Other nstf_utility: check_covr_skip_nstf(), check_covr_skip_testit(), get_nstf_test_path(), 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 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)

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_name, env = cov_env)

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 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()

Prepare a BioC/RUnit package for testing

Description

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)

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

Usage

remove_run_unitTests_mapping(mapping, test_pkg_data)

Arguments

Value

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

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)

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 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)

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_nstf(), check_covr_skip_testit(), get_nstf_test_path(), get_source_test_mapping_nstf()

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()

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)

Setup coverage environment using an existing cov_env (CRAN-safe)

Description

NOTE: - This function no longer creates 'cov_env' nor writes helper files into tests/. - Pass an environment (e.g., from initialise_covr_env()) via 'cov_env'. - All writes by downstream helpers should target cov_env$work_dir (under tempdir()).

Usage

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

Arguments

Value

list(cov_env, datasets_loaded, root_dir, initial_state, helpers_loaded)

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.