Learn R Programming

covr

Track test coverage for your R package and view reports locally or (optionally) upload the results to codecov or coveralls.

Installation

install.packages("covr")

# For devel version
devtools::install_github("r-lib/covr")

The easiest way to setup covr on Github Actions is with usethis.

usethis::use_github_action("test-coverage")

Usage

For local development a coverage report can be used to inspect coverage for each line in your package. Note requires the DT package to be installed.

library(covr)

# If run with no arguments implicitly calls `package_coverage()`
report()

covr also defines an RStudio Addin, which runs report() on the active project. This can be used via the Addin menu or by binding the action to a shortcut, e.g. Ctrl-Shift-C.

Interactively

# If run with the working directory within the package source.
package_coverage()

# or a package in another directory
cov <- package_coverage("/dir/lintr")

# view results as a data.frame
as.data.frame(cov)

# zero_coverage() shows only uncovered lines.
# If run within RStudio, `zero_coverage()` will open a marker pane with the
# uncovered lines.
zero_coverage(cov)

Exclusions

covr supports a few of different ways of excluding some or all of a file.

.covrignore file

A .covrignore file located in your package's root directory can be used to exclude files or directories.

The lines in the .covrignore file are interpreted as a list of file globs to ignore. It uses the globbing rules in Sys.glob(). Any directories listed will ignore all the files in the directory.

Alternative locations for the file can be set by the environment variable COVR_COVRIGNORE or the R option covr.covrignore.

The .covrignore file should be added to your .RBuildignore file unless you want to distribute it with your package. If so it can be added to inst/.covrignore instead.

Function Exclusions

The function_exclusions argument to package_coverage() can be used to exclude functions by name. This argument takes a vector of regular expressions matching functions to exclude.

# exclude print functions
package_coverage(function_exclusions = "print\\.")

# exclude `.onLoad` function
package_coverage(function_exclusions = "\\.onLoad")

Line Exclusions

The line_exclusions argument to package_coverage() can be used to exclude some or all of a file. This argument takes a list of filenames or named ranges to exclude.

# exclude whole file of R/test.R
package_coverage(line_exclusions = "R/test.R")

# exclude lines 1 to 10 and 15 from R/test.R
package_coverage(line_exclusions = list("R/test.R" = c(1:10, 15)))

# exclude lines 1 to 10 from R/test.R, all of R/test2.R
package_coverage(line_exclusions = list("R/test.R" = c(1, 10), "R/test2.R"))

Exclusion Comments

In addition you can exclude lines from the coverage by putting special comments in your source code.

This can be done per line.

f1 <- function(x) {
  x + 1 # nocov
}

Or by specifying a range with a start and end.

f2 <- function(x) { # nocov start
  x + 2
} # nocov end

The patterns used can be specified by setting the global options covr.exclude_pattern, covr.exclude_start, covr.exclude_end.

NB: The same pattern applies to exclusions in the src folder, so skipped lines in, e.g., C code (where comments can start with //) should look like // # nocov.

FAQ

Will covr work with testthat, RUnit, etc...

Covr should be compatible with any testing package, it uses tools::testInstalledPackage() to run your packages tests.

Will covr work with alternative compilers such as ICC

Covr now supports Intel's icc compiler, thanks to work contributed by Qin Wang at Oracle.

Covr is known to work with clang versions 3.5+ and gcc version 4.2+.

If the appropriate gcov version is not on your path you can set the appropriate location with the covr.gcov options. If you set this path to "" it will turn off coverage of compiled code.

options(covr.gcov = "path/to/gcov")

How does covr work?

covr tracks test coverage by modifying a package's code to add tracking calls to each call.

The vignette vignettes/how_it_works.Rmd contains a detailed explanation of the technique and the rationale behind it.

You can view the vignette from within R using

vignette("how_it_works", package = "covr")

Why can't covr run during R CMD check

Because covr modifies the package code it is possible there are unknown edge cases where that modification affects the output. In addition when tracking coverage for compiled code covr compiles the package without optimization, which can modify behavior (usually due to package bugs which are masked with higher optimization levels).

Alternative Coverage Tools

Code of Conduct

Please note that the covr project is released with a Contributor Code of Conduct. By contributing to this project, you agree to abide by its terms.

Copy Link

Version

Install

install.packages('covr')

Monthly Downloads

139,672

Version

3.6.4

License

MIT + file LICENSE

Issues

Pull Requests

Stars

Forks

Maintainer

Last Published

November 9th, 2023

Functions in covr (3.6.4)

environment_coverage

Calculate coverage of an environment
has_srcref

Is the source bound to the expression
print.coverage

Print a coverage object
is_covr_count_call

Is the expression a call to covr:::count
to_cobertura

Create a Cobertura XML file
value

Retrieve the value from an object
zero_coverage

Provide locations of zero coverage
report

Display covr results using a standalone report
tally_coverage

Tally coverage by line or expression
in_covr

Determine if code is being run in covr
to_sonarqube

Create a SonarQube Generic XML file for test coverage according to https://docs.sonarqube.org/latest/analysis/generic-test/ Based on cobertura.R
is_current_test_finished

Returns TRUE if we've moved on from test reflected in .current_test
key

Generate a key for a call
trace_calls

trace each call with a srcref attribute
percent_coverage

Provide percent coverage of package
package_coverage

Calculate test coverage for a package
new_test_counter

Initialize a new test counter for a coverage trace
system_output

Run a system command and capture the output.
new_counter

initialize a new counter
system_check

Run a system command and check if it succeeds.
truncate_call

Truncate call objects to limit the number of arguments
update_current_test

Update current test if unit test expression has progressed
codecov

Run covr on a package and upload the result to codecov.io
count

increment a given counter
azure

Run covr on a package and output the result so it is available on Azure Pipelines
code_coverage

Calculate coverage of code directly
coverage_to_list

Convert a coverage dataset to a list
as_coverage

Convert a counters object to a coverage object
coveralls

Run covr on a package and upload the result to coveralls
as_coverage_with_tests

Clean and restructure counter tests for a coverage object
gitlab

Run covr on package and create report for GitLab
covr.record_tests

Record Test Traces During Coverage Execution
file_coverage

Calculate test coverage for sets of files
covr-package

covr: Test coverage for packages
exclusions

Exclusions
clear_counters

clear all previous counters
display_name

Retrieve the path name (filename) for each coverage object
count_test

Append a test trace to a counter, updating global current test
file_report

A coverage report for a specific file
function_coverage

Calculate test coverage for a specific function.