The functions in env are instrumented, then the files in test_files are
run with sys.source() in a child environment of env, from the current
working directory. Nothing else is set up, so testthat tests that rely on
its test runner, e.g. for setup files, snapshots, or the test directory as
the working directory (which testthat::test_path() uses to find fixtures
while testing), should instead be run with testthat::test_file() inside
with_coverage().
environment_coverage(
env = parent.frame(),
test_files,
line_exclusions = NULL,
function_exclusions = NULL
)A coverage object.
The environment to be instrumented.
Character vector of test files with code to test the functions
a named list of files with the lines to exclude from each file.
a vector of regular expressions matching function
names to exclude. Example print\\\. to match print methods.
Code run in processes forked by parallel::mclapply(),
parallel::mcparallel() and related functions (not available on Windows)
is included in the coverage. While the code runs, parallel:::mcfork and
parallel:::mcexit are patched so that the forked processes save their
counts when they exit. To turn this off, set the option
covr.fix_parallel_mcexit or the environment variable
COVR_FIX_PARALLEL_MCEXIT to FALSE.
environment_coverage() and with_coverage() include the compiled code in
the coverage of the namespace of a package loaded with pkgload::load_all()
(e.g. by devtools::load_all()), so devtools::test_coverage_active_file()
also works for files in src/. With compiled files in source_files,
file_coverage() loads their package with pkgload::load_all() and reports
the coverage of those files, without needing devtools:
file_coverage("src/foo.c", "tests/testthat/test-foo.R")
file_coverage("src/rust/src/lib.rs", "tests/testthat/test-foo.R")
The compiled code is measured in the current session, which is much faster
than package_coverage(): C, C++, Fortran and Objective-C code with gcov,
and Rust code (e.g. of packages using extendr or savvy) with LLVM's
source-based coverage, which needs the llvm tools described in
package_coverage(). An instrumented copy of the package is built in the
session's temporary directory, leaving the package's own build untouched,
and later runs only recompile the files that changed, with cargo's
incremental build in the copy's own target directory for Rust code.
While the code runs, the namespace's native routines use the instrumented
DLL instead of the package's own. Routines that were looked up some other
way, e.g. stored by .onLoad() or found by other packages with
R_GetCCallable(), keep using the package's DLL, so their code isn't
counted. Set options(covr.gcov = "") to leave out C, C++, Fortran and
Objective-C code, and options(covr.llvm_cov = "") to leave out Rust code.
with_coverage()