Skip to content

r-lib/covr

main
Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?
Code

Latest commit

 

Git stats

Files

Permalink
Failed to load latest commit information.
Type
Name
Latest commit message
Commit time
September 21, 2018 12:25
March 6, 2020 11:48
src
June 26, 2017 11:10
August 26, 2022 09:37
August 26, 2022 08:29
March 6, 2020 11:48
February 20, 2015 09:15
January 19, 2022 12:31
January 19, 2022 12:31
June 26, 2017 08:19
August 26, 2022 08:29
August 26, 2022 09:42
April 15, 2021 09:52
March 29, 2021 12:44
August 28, 2019 10:59
August 26, 2022 08:29
August 9, 2019 06:55
August 9, 2019 06:55

covr

R-CMD-check Codecov test coverage CRAN version

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.