covr v3.0.0

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' <http://codecov.io> or 'Coveralls' <http://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.

Readme

Covr

Build Status AppVeyor Build Status codecov.io CRAN version

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

Installation

Codecov

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

r_github_packages:
  - jimhester/covr

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

To use a different CI service or call codecov() locally you can set the environment variable CODECOV_TOKEN to the token generated on codecov.io.

Codecov currently has support for the following CI systems (* denotes support without needing CODECOV_TOKEN).

You will also need to enable the repository on Codecov.

Coveralls

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

r_github_packages:
  - jimhester/covr

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.

Interactive Usage

Shiny Application

A shiny Application can be used to view coverage per line.

cov <- package_coverage()

shine(cov)

If used with type = "all", combine_types = FALSE the Shiny Application will allow you to interactively toggle between Test, Vignette and Example coverage.

cov <- package_coverage(type = "all", combine_types = FALSE)

shine(cov)

R Command Line

# if your working directory is in the packages base directory
package_coverage()

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

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

# zero_coverage() can be used to filter only uncovered lines.
zero_coverage(cov)

Exclusions

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

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.

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
codecov Run covr on a package and upload the result to codecov.io
count increment a given counter
coveralls Run covr on a package and upload the result to coveralls
exclusions Exclusions
tally_coverage Tally coverage by line or expression
to_cobertura Create a Cobertura XML file
key Generate a key for a call
new_counter initialize a new counter
print.coverage Print a coverage object
report Display covr results using a standalone report
zero_coverage Provide locations of zero coverage
file_coverage Calculate test coverage for sets of files
function_coverage Calculate test coverage for a specific function.
system_check Run a system command and check if it succeeds.
trace_calls trace each call with a srcref attribute
value Retrieve the value from an object
system_output Run a system command and capture the output.
clear_counters clear all previous counters
code_coverage Calculate coverage of code directly
package_coverage Calculate test coverage for a package
percent_coverage Provide percent coverage of package
No Results!

Vignettes of covr

Name
how_it_works.Rmd
No Results!

Last month downloads

Details

Include our badge in your README

[![Rdoc](http://www.rdocumentation.org/badges/version/covr)](http://www.rdocumentation.org/packages/covr)