# covr v3.5.1

0

Monthly downloads

0th

Percentile

## Test Coverage for Packages

Track and report code coverage for your package and (optionally) upload the results to a coverage service like 'Codecov' <https://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 code.

# 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 Travis-CI is with usethis.

usethis::use_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)


# Automated reports

## Codecov

If you are already using Travis-CI add the following to your project's .travis.yml to track your coverage results over time with Codecov.

after_success:
- Rscript -e 'covr::codecov()'


If you are using Appveyor CI then you can add the lines below to your project's appveyor.yml:

on_success:
- Rscript -e "covr::codecov()"


You also need to install covr, either by adding it to the Suggests: field of your package's DESCRIPTION file or also to Remotes: r-lib/covr if you want to install the development version.

To use other CI services or if you want to upload a coverage report locally you can set environment variable CODECOV_TOKEN to the token generated on the settings page of https://codecov.io.

## Coveralls

Alternatively you can upload your results to Coveralls using covr::coveralls().

after_success:
- Rscript -e 'covr::coveralls()'


For CI systems not supported by coveralls you need to set the COVERALLS_TOKEN environment variable. It is wise to use a Secure Variable so that it is not revealed publicly.

Also you will need to turn on coveralls for your project at https://coveralls.io/repos.

# 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

## Functions in covr

 Name Description file_report A coverage report for a specific file value Retrieve the value from an object exclusions Exclusions file_coverage Calculate test coverage for sets of files covr-package covr: Test coverage for packages zero_coverage Provide locations of zero coverage print.coverage Print a coverage object function_coverage Calculate test coverage for a specific function. report Display covr results using a standalone report new_counter initialize a new counter package_coverage Calculate test coverage for a package gitlab Run covr on package and create report for GitLab key Generate a key for a call percent_coverage Provide percent coverage of package in_covr Determine if code is being run in covr tally_coverage Tally coverage by line or expression system_check Run a system command and check if it succeeds. to_cobertura Create a Cobertura XML file 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 trace_calls trace each call with a srcref attribute system_output Run a system command and capture the output. codecov Run covr on a package and upload the result to codecov.io environment_coverage Calculate coverage of an environment clear_counters clear all previous counters 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 coveralls Run covr on a package and upload the result to coveralls count increment a given counter display_name Retrieve the path name (filename) for each coverage object No Results!

## Vignettes of covr

 Name how_it_works.Rmd No Results!

## Details

 Encoding UTF-8 URL https://covr.r-lib.org, https://github.com/r-lib/covr BugReports https://github.com/r-lib/covr/issues License GPL-3 LazyData true VignetteBuilder knitr RoxygenNote 7.1.0 NeedsCompilation yes Packaged 2020-09-16 20:09:53 UTC; jhester Repository CRAN Date/Publication 2020-09-16 21:10:13 UTC
 imports crayon , digest , httr , jsonlite , rex , stats , utils , withr (>= 1.0.2) , yaml suggests curl , DT (>= 0.2) , htmltools , knitr , memoise , mockery , parallel , R6 , rlang , rmarkdown , rstudioapi (>= 0.2) , testthat , xml2 (>= 1.0.0) depends methods , R (>= 3.1.0) Contributors Chris Campbell, Jeroen Ooms, Henrik Bengtsson, Jon Clayden, Ken Williams, Willem Ligtenberg, Jouni Helske, Kirill Mller, Will Beasley, Robert Krzyzanowski, Mark Otto, Jacob Thornton, Ivan Sagalaev, Eric Brown, Markus Wamser, Steve Peak, Kirill Sevastyanenko, Robert Flight, Brodie Gaslam, Karl Forner, Kun Ren, Bootstrap contributors, Twitter, Inc, David Hugh-Jones, Gergely Darczi, Qin Wang