Learn R Programming

covr (version 4.0.0)

with_coverage: Calculate coverage of arbitrary code run against an environment

Description

with_coverage() instruments the functions in env, evaluates code, and returns the coverage that code produced. Unlike environment_coverage(), which sys.source()s a set of files, code can be any expression. This makes it possible to measure coverage while running tests with a test runner such as testthat::test_file(), without having to recreate the runner's infrastructure (reporters, snapshot handling, test environment, ...).

Usage

with_coverage(
  code,
  env = parent.frame(),
  line_exclusions = NULL,
  function_exclusions = NULL
)

Value

A coverage object.

Arguments

code

The code to evaluate while measuring coverage. It is evaluated lazily, in the calling environment, after env has been instrumented.

env

The environment to be instrumented, e.g. a package namespace.

line_exclusions

a named list of files with the lines to exclude from each file.

function_exclusions

a vector of regular expressions matching function names to exclude. Example print\\\. to match print methods.

Parallel code

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.

Compiled code

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.

Details

Functions are instrumented in place, so every existing reference to them, including ones captured by an environment created by code (e.g. the child environment of the namespace that testthat::test_file() evaluates tests in), runs the instrumented version. The only requirement is that code must not re-create the functions in env, e.g. when using testthat::test_file() with package set the package must not be reloaded (use load_package = "none"), as reloading would replace the instrumented functions with fresh, uninstrumented ones.

The instrumentation is removed and the counters are cleared when with_coverage() exits, even if code fails.

See Also

environment_coverage()

Examples

Run this code
if (FALSE) {
# With a package loaded by pkgload::load_all()
ns <- asNamespace("mypkg")
with_coverage(
  testthat::test_file(
    "tests/testthat/test-foo.R",
    package = "mypkg",
    load_package = "none"
  ),
  env = ns
)
}

Run the code above in your browser using DataLab