covr tracks and reports code coverage for your package and (optionally) upload the results to a coverage service like 'Codecov' https://about.codecov.io or 'Coveralls' https://coveralls.io. Code coverage is a measure of the amount of code being exercised by a set of tests. It is an indirect measure of test quality and completeness. This package is compatible with any testing methodology or framework and tracks coverage of both R code and compiled C, C++, Fortran and Rust code.
covr uses the following options() to configure behaviour:
covr.branch_coverage: If TRUE (default FALSE), also record
which branches of each if and switch() in R code were taken. This
is experimental. It must be set before the code is instrumented, e.g.
before calling package_coverage(). For more details, see
?covr.branch_coverage.
covr.covrignore: A filename to use as an ignore file,
listing glob-style wildcarded paths of files to ignore for coverage
calculations. Defaults to the value of the environment variable
COVR_COVRIGNORE, or ".covrignore" if neither the option nor the
environment variable is set.
covr.exclude_end: Used along with covr.exclude_start, an optional
regular expression which ends a line-exclusion region. For more
details, see ?exclusions.
covr.exclude_pattern: An optional line-exclusion pattern. Lines
which match the pattern will be excluded from coverage. For more details,
see ?exclusions.
covr.exclude_start: Used along with covr.exclude_end, an optional
regular expression which starts a line-exclusion region. For more
details, see ?exclusions.
covr.filter_non_package: If TRUE (the default behavior), coverage
of files outside the target package are filtered from coverage output.
covr.failure_lines: The number of trailing lines of test output
shown in the message and print() method of a covr_error when tests,
vignettes, examples or code fail (default 50). The full output is
always available in the condition's $output field.
covr.allow_failures: If TRUE (default FALSE), failures or
errors when running the tests, vignettes, examples or code of
package_coverage() are reported as warnings and coverage is still
returned, the default of its allow_failures argument.
covr.annotate_max_lines: The maximum number of source lines shown
by annotate_coverage() (default 200), the default of its max_lines
argument. Inf shows everything.
covr.print_max_ranges: The maximum number of missed ranges, and of
missed branches, listed per file or function by print(x, missing = TRUE) (default 10). More are summarised as ... (<k> more). Inf
lists them all.
covr.fix_parallel_mcexit: Whether to include code run in processes
forked by parallel's mclapply(), mcparallel() and related
functions, by patching parallel:::mcexit. By default
package_coverage() does this if the package uses parallel, and
the functions that measure coverage in the current session, such as
file_coverage(), always do. Can also be set with the environment
variable COVR_FIX_PARALLEL_MCEXIT. Not supported on Windows.
covr.flags: A named character vector of the compiler and linker
settings (the values of a Makevars file, e.g. CFLAGS) that are added
when package_coverage() installs a package, or file_coverage()
builds one, for coverage of compiled code. The default, set when covr
is loaded, compiles C, C++ and Fortran code without optimization and
with --coverage ("-O0 --coverage") and links it to gcov (FLIBS is
"-lgcov", LDFLAGS or on Windows SHLIB_LIBADD is "--coverage").
covr.gcov: Path to the gcov executable. Defaults to the gcov found
on your PATH, or NA if there is none. If the appropriate gcov version
is not on your path you can use this option to set the appropriate
location. If set to "" it will turn off coverage of C, C++ and Fortran
code, but not of Rust code, which is controlled by covr.llvm_cov. If
NA, covr throws an error if any compiled coverage files (.gcno)
exist.
covr.gcov_additional_paths: A character vector of directories,
in addition to the package itself, whose compiled source files (C, C++,
Fortran or Rust) are accepted in the coverage, e.g. the code of another
package or library that is compiled into the package from outside of its
src/ directory. Files elsewhere are left out. Default NULL.
covr.gcov_args: A character vector of additional command line
arguments passed to gcov. Default NULL.
covr.gcov_partial: How to count compiled code lines that gcov
reports as only partially executed (e.g. if (x) f(); when f() never
runs). "covered" (the default) counts them as covered, "uncovered"
counts them as not covered, for requiring every part of a line to run.
This works with both gcc's gcov and llvm-cov (the gcov on macOS).
llvm-cov can't tell apart code that only runs when a C++ exception is
thrown, so lines that create objects with destructors may also count as
partially executed.
covr.llvm_cov: Path to the llvm-cov used to read the coverage
of Rust code. Defaults to the one of the Rust toolchain, installed with
rustup component add llvm-tools, or for Rust installed without rustup
(e.g. with apt-get install cargo rustc), to the one on the PATH with
the same LLVM version as rustc, e.g. llvm-cov-18. If set to "" the
Rust code isn't instrumented, which turns off its coverage. This is
independent of covr.gcov, which only controls C, C++ and Fortran code.
covr.llvm_profdata: Path to the llvm-profdata used to merge the
coverage counts of Rust code. Found like covr.llvm_cov.
covr.report_colors: A named character vector with the colors of
covered and missed lines in report() and file_report(), and of the
coverage percentages printed in the console, e.g.
c(covered = "#0072B2", missed = "#D55E00"). colorblind_palette has
colors that are easier to tell apart than the default green and red
with color vision deficiency. Either element can be left out to keep
its default.
An optional partial element sets the color of partial coverage (at
least 75% but less than 90%), which otherwise follows covered, or is
yellow in the console if covered isn't set either, and of lines with
a branch that wasn't taken in reports with branch coverage, which are
otherwise yellow. Transparency is ignored. In terminals with only 8
colors, the console uses the closest of those colors.
covr.rstudio_source_markers: A logical value. If TRUE (the
default behavior), source markers are displayed within the RStudio IDE
when using zero_coverage.
covr.record_tests: If TRUE (default FALSE), record a listing
of top level test expressions and associate tests with covr traces
evaluated during the test's execution. For more details, see
?covr.record_tests.
covr.full_traversal: If TRUE (default FALSE), also trace
functions nested inside lists and environments, such as
fns <- list(a = function(x) x) or functions defined inside local().
This walks every object in the package, so it is off by default. For
package_coverage() it can also be enabled for a package by adding
Config/covr/full_traversal: true to its DESCRIPTION; the option takes
precedence when set.
covr.install_instrument: If FALSE (default TRUE),
package_coverage() installs a package as usual and instruments it each
time a process loads it, rather than once after installing it. Can also
be set with the environment variable COVR_INSTALL_INSTRUMENT.
Some options can also be set with an environment variable. They are read in
this order: the option, then the environment variable (ignored if it is
empty), then the default. So an option set in R always takes precedence over
the environment variable, e.g. COVR_FIX_PARALLEL_MCEXIT=false has no
effect if options(covr.fix_parallel_mcexit = TRUE) is set. Logical
settings are TRUE or FALSE, or for the environment variable (and
options set to a string), one of true, t, yes or 1, and false,
f, no or 0, in any case. Other values are ignored with a warning.
Maintainer: Jim Hester [email protected]
Authors:
Jim Hester [email protected]
Other contributors:
Willem Ligtenberg [contributor]
Kirill Müller [contributor]
Henrik Bengtsson [contributor]
Steve Peak [contributor]
Kirill Sevastyanenko [contributor]
Jon Clayden [contributor]
Robert Flight [contributor]
Eric Brown [contributor]
Brodie Gaslam [contributor]
Will Beasley [contributor]
Robert Krzyzanowski [contributor]
Markus Wamser [contributor]
Karl Forner [contributor]
Gergely Daróczi [contributor]
Jouni Helske [contributor]
Kun Ren [contributor]
Jeroen Ooms [contributor]
Ken Williams [contributor]
Chris Campbell [contributor]
David Hugh-Jones [contributor]
Qin Wang [contributor]
Doug Kelkhoff [contributor]
Ivan Sagalaev (highlight.js library) [contributor, copyright holder]
A coverage report can be used to inspect coverage for each line in your
package. Using report() requires the additional dependency htmltools.
# If run with no arguments `report()` implicitly calls `package_coverage()`
report()
Useful links: