Repository files navigation

Track test coverage for your R package and view reports locally or (optionally)upload the results tocodecov orcoveralls.

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

The easiest way to setup covr onGithub Actionsis withusethis.

usethis::use_github_action("test-coverage")

For local development a coverage report can be used to inspect coverage foreach line in your package.Note requires theDT package to be installed.

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

covr also defines anRStudio Addin,which runsreport() on the active project. This can be used via the Addinmenu or by binding the action to ashortcut, e.g.Ctrl-Shift-C.

# 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)

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

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

The lines in the.covrignore file are interpreted as a list of file globs toignore. It uses the globbing rules inSys.glob(). Any directories listed willignore 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 youwant to distribute it with your package. If so it can be added toinst/.covrignore instead.

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

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

Theline_exclusions argument topackage_coverage() can be used to exclude some orall of a file. This argument takes a list of filenames or named ranges toexclude.

# 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"))

In addition you can exclude lines from the coverage by putting special commentsin 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.

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

Covr now supports Intel'sicc compiler, thanks to work contributed by QinWang 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 appropriatelocation with thecovr.gcov options. If you set this path to "" it will turnoff coverage of compiled code.

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

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

The vignettevignettes/how_it_works.Rmdcontains 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")

Because covr modifies the package code it is possible there are unknown edgecases where that modification affects the output. In addition when trackingcoverage for compiled code covr compiles the package without optimization,whichcan modify behavior (usually due to package bugs which are masked withhigher optimization levels).

• https://github.com/MangoTheCat/testCoverage (no longer supported)
• R-coverage (no longer supported)

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.