prepare_tinytest_run_env: Enable environment-gated tinytest suites (internal)

In test.assessr: Assessing Package Test Reliability and Quality

Enable environment-gated tinytest suites (internal)

Description

Some packages gate their entire tinytest suite behind environment variables, exiting each test file early via tinytest::exit_file() unless a variable is set to a specific value. Rcpp is the canonical example: every file under inst/tinytest begins with a guard such as if (Sys.getenv("RunAllRcppTests") != "yes") exit_file(...), so a plain tinytest::run_test_dir() executes zero tests and reports 0% coverage.

Usage

prepare_tinytest_run_env(tiny_dir, max_files = 40L, header_lines = 60L)

Arguments

tiny_dir	Character scalar. Path to the tinytest directory (typically inst/tinytest).
max_files	Integer scalar. Maximum number of test files to scan. Defaults to 40L.
header_lines	Integer scalar. Number of lines read from the top of each test file when searching for gates. Defaults to 60L.

Details

This helper scans the headers of the discovered test files for gate patterns of the form Sys.getenv("VAR") != "VALUE" and sets the discovered variables to their required values so the tests run during coverage. It is generic: any package using this idiom (not only Rcpp) benefits without hard-coding package names. Packages without such gates (e.g. digest) produce no matches, so nothing is changed and behaviour is identical to before.

Both gate idioms are recognised: the primary “exit unless opted in” form (Sys.getenv("VAR") != "VALUE") and the complementary == "VALUE" form used for secondary “verbose” suites (e.g. RunVerboseRcppTests). In both cases the suite runs only when VAR == VALUE, so the variable is set to that value. Verbose suites exercise packaging helpers in-process (which covr can trace) but may also run R CMD build / install.packages in child processes that can fail; create_tinytest_coverage() therefore drives test files in isolation so one failure cannot stop the run.

The function is intentionally defensive and never throws: on any problem it returns a no-op result so the surrounding tinytest coverage path is unaffected. Callers should register the returned teardown via on.exit() to restore the previous environment state.

Value

A list with components:

set_vars

Named character vector of environment variables that were set (variable name to required value); empty when no gates are found.

teardown

A function that restores the previous environment state (unsetting variables that were previously unset).

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(), prepare_tinytest_dev_includes(), restrict_test_paths_to_framework(), run_covr_skip_nstf()

test.assessr documentation built on July 16, 2026, 5:07 p.m.