covr

install.packages("covr")# For devel versiondevtools::install_github("r-lib/covr")

usethis::use_github_action("test-coverage")

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

Interactively

# If run with the working directory within the package source.package_coverage()# or a package in another directorycov<-package_coverage("/dir/lintr")# view results as a data.frameas.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)

.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 inSys.glob(). Any directories listed will ignore all the files in the directory.

Alternative locations for the file can be set by the environment variableCOVR_COVRIGNORE or the R optioncovr.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 toinst/.covrignore instead.

Function Exclusions

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

# exclude print functionspackage_coverage(function_exclusions="print\\.")# exclude `.onLoad` functionpackage_coverage(function_exclusions="\\.onLoad")

Line Exclusions

Theline_exclusions argument topackage_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.Rpackage_coverage(line_exclusions="R/test.R")# exclude lines 1 to 10 and 15 from R/test.Rpackage_coverage(line_exclusions=list("R/test.R"=c(1:10,15)))# exclude lines 1 to 10 from R/test.R, all of R/test2.Rpackage_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 startx+2}# nocov end

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

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

Will covr work with testthat, RUnit, etc…

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

Will covr work with alternative compilers such as ICC

Covr now supports Intel’sicc compiler, thanks to work contributed by Qin Wang at Oracle.

Covr is known to work with clang versions3.5+ and gcc version4.2+.

If the appropriate gcov version is not on your path you can set the appropriate location with thecovr.gcov options. If you set this path to “” it will turnoff 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 vignettevignettes/how_it_works.Rmd contains a detailed explanation of the technique and the rationale behind it.

You can view the vignette from withinR 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, whichcan modify behavior (usually due to package bugs which are masked with higher optimization levels).

Code of Conduct

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