covr - Test Coverage for R Packages


Being primarily a statistical language R lacks a number of common code analysis tools available for languages used more often for general programming. Testing has been done in the R source from very early on (Martin Maechler started adding tests on April 9th, 1998, 17 years ago!) However most of this testing was ad hoc, either requiring visual examination of the outputs, or simply testing current vs previous outputs. The RUnit (2005), svUnit (2009) and testthat (2009) packages brought more formal unit testing into R community.

So while tools existed to show authors how to test, there were very limited tools to show what to test. Code coverage has a very long history (Miller et al. 1963) in the software development community and remains a useful metric today. Unfortunately the R community has had very few options to track and report on code coverage. R-coverage by Karl Forner and testCoverage by Tom Taverner, Chris Campbell, Suchen Jin were two existing solutions, however both were somewhat problematic to use. The former required a patch to the R source, which is a non-starter for widespread use (particularly on Windows). The latter had a complicated implementation which was difficult to use interactively and supported only a limited output format. Neither project supported tracking coverage of compiled code in addition to R source or supported coverage tracking services such as http://codecov.io or http://coveralls.io.

Covr aims to make code coverage both easy to use and informative in R. Package coverage can be tracked and tests run very simply

library(covr)
cov <- package_coverage()

The results can be summarized with an informative print() method, as well as coerced to a data.frame. There is also an interactive Shiny App available via shine() which can be used to inspect the code visually and identify coverage gaps.

In addition covr supports both the http://codecov.io and http://coveralls.io coverage reporting services. These services will track the coverage of a project over time and report on coverage changes as well as exploration of the source code. They are designed to work seamlessly within a CI system such as https://travis-ci.org/ or http://wercker.com/. Simple functions exist to instrument the code, run tests and submit the results for both services and can easily be added to the CI build script to automatically run coverage for every build.

library(covr)
# for codecov.io
codecov()

# for coveralls.io
coveralls()

Covr version 1.0.0 is now on CRAN and Covr development is ongoing at https://github.com/jimhester/covr, pull requests for additional features or bug fixes are always welcome!


Comments