| Title: | Test Coverage for Packages |
| Version: | 4.0.0 |
| Description: | Track and report code coverage for your package and (optionally) upload the results to a coverage service like 'Codecov' https://about.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 and Rust code. |
| License: | MIT + file LICENSE |
| URL: | https://covr.r-lib.org, https://github.com/r-lib/covr |
| BugReports: | https://github.com/r-lib/covr/issues |
| Depends: | methods, R (≥ 4.1.0) |
| Imports: | cli (≥ 2.5.0), curl, digest, grDevices, httr2 (≥ 1.0.4), jsonlite, rex, rlang, stats, sys (≥ 3.0), utils, withr (≥ 1.0.2), yaml |
| Suggests: | box (≥ 1.2.0), callr, compiler, covr, htmltools, knitr, memoise, parallel, pkgbuild, pkgload, R6, rmarkdown, rstudioapi (≥ 0.2), S7 (≥ 0.2.0), shiny, shinytest2, testthat (≥ 3.0.0), xml2 (≥ 1.0.0) |
| VignetteBuilder: | knitr |
| Config/roxygen2/version: | 8.1.1 |
| Config/testthat/edition: | 3 |
| Config/testthat/parallel: | TRUE |
| Encoding: | UTF-8 |
| NeedsCompilation: | yes |
| Packaged: | 2026-11-15 22:06:22 UTC; jimhester |
| Author: | Jim Hester [aut, cre], Willem Ligtenberg [ctb], Kirill Müller [ctb], Henrik Bengtsson [ctb], Steve Peak [ctb], Kirill Sevastyanenko [ctb], Jon Clayden [ctb], Robert Flight [ctb], Eric Brown [ctb], Brodie Gaslam [ctb], Will Beasley [ctb], Robert Krzyzanowski [ctb], Markus Wamser [ctb], Karl Forner [ctb], Gergely Daróczi [ctb], Jouni Helske [ctb], Kun Ren [ctb], Jeroen Ooms [ctb], Ken Williams [ctb], Chris Campbell [ctb], David Hugh-Jones [ctb], Qin Wang [ctb], Doug Kelkhoff [ctb], Ivan Sagalaev [ctb, cph] (highlight.js library) |
| Maintainer: | Jim Hester <james.f.hester@gmail.com> |
| Repository: | CRAN |
| Date/Publication: | 2026-11-16 09:30:02 UTC |
covr: Test coverage for packages
Description
covr tracks and reports code coverage for your package and (optionally) upload the results to a coverage service like 'Codecov' https://about.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 and Rust code.
Details
A coverage report can be used to inspect coverage for each line in your
package. Using report() requires the additional dependency htmltools.
# If run with no arguments `report()` implicitly calls `package_coverage()` report()
Package options
covr uses the following options() to configure behaviour:
-
covr.branch_coverage: IfTRUE(defaultFALSE), also record which branches of eachifandswitch()in R code were taken. This is experimental. It must be set before the code is instrumented, e.g. before callingpackage_coverage(). For more details, see?covr.branch_coverage. -
covr.covrignore: A filename to use as an ignore file, listing glob-style wildcarded paths of files to ignore for coverage calculations. Defaults to the value of the environment variableCOVR_COVRIGNORE, or".covrignore"if neither the option nor the environment variable is set. -
covr.exclude_end: Used along withcovr.exclude_start, an optional regular expression which ends a line-exclusion region. For more details, see?exclusions. -
covr.exclude_pattern: An optional line-exclusion pattern. Lines which match the pattern will be excluded from coverage. For more details, see?exclusions. -
covr.exclude_start: Used along withcovr.exclude_end, an optional regular expression which starts a line-exclusion region. For more details, see?exclusions. -
covr.filter_non_package: IfTRUE(the default behavior), coverage of files outside the target package are filtered from coverage output. -
covr.failure_lines: The number of trailing lines of test output shown in the message andprint()method of acovr_errorwhen tests, vignettes, examples orcodefail (default50). The full output is always available in the condition's$outputfield. -
covr.allow_failures: IfTRUE(defaultFALSE), failures or errors when running the tests, vignettes, examples orcodeofpackage_coverage()are reported as warnings and coverage is still returned, the default of itsallow_failuresargument. -
covr.annotate_max_lines: The maximum number of source lines shown byannotate_coverage()(default200), the default of itsmax_linesargument.Infshows everything. -
covr.print_max_ranges: The maximum number of missed ranges, and of missed branches, listed per file or function byprint(x, missing = TRUE)(default10). More are summarised as... (<k> more).Inflists them all. -
covr.fix_parallel_mcexit: Whether to include code run in processes forked by parallel'smclapply(),mcparallel()and related functions, by patchingparallel:::mcexit. By defaultpackage_coverage()does this if the package uses parallel, and the functions that measure coverage in the current session, such asfile_coverage(), always do. Can also be set with the environment variableCOVR_FIX_PARALLEL_MCEXIT. Not supported on Windows. -
covr.flags: A named character vector of the compiler and linker settings (the values of aMakevarsfile, e.g.CFLAGS) that are added whenpackage_coverage()installs a package, orfile_coverage()builds one, for coverage of compiled code. The default, set when covr is loaded, compiles C, C++ and Fortran code without optimization and with--coverage("-O0 --coverage") and links it to gcov (FLIBSis"-lgcov",LDFLAGSor on WindowsSHLIB_LIBADDis"--coverage"). -
covr.gcov: Path to the gcov executable. Defaults to the gcov found on yourPATH, orNAif there is none. If the appropriate gcov version is not on your path you can use this option to set the appropriate location. If set to""it will turn off coverage of C, C++ and Fortran code, but not of Rust code, which is controlled bycovr.llvm_cov. IfNA, covr throws an error if any compiled coverage files (.gcno) exist. -
covr.gcov_additional_paths: A character vector of directories, in addition to the package itself, whose compiled source files (C, C++, Fortran or Rust) are accepted in the coverage, e.g. the code of another package or library that is compiled into the package from outside of itssrc/directory. Files elsewhere are left out. DefaultNULL. -
covr.gcov_args: A character vector of additional command line arguments passed to gcov. DefaultNULL. -
covr.gcov_partial: How to count compiled code lines that gcov reports as only partially executed (e.g.if (x) f();whenf()never runs)."covered"(the default) counts them as covered,"uncovered"counts them as not covered, for requiring every part of a line to run. This works with both gcc's gcov and llvm-cov (the gcov on macOS). llvm-cov can't tell apart code that only runs when a C++ exception is thrown, so lines that create objects with destructors may also count as partially executed. -
covr.llvm_cov: Path to thellvm-covused to read the coverage of Rust code. Defaults to the one of the Rust toolchain, installed withrustup component add llvm-tools, or for Rust installed without rustup (e.g. withapt-get install cargo rustc), to the one on thePATHwith the same LLVM version as rustc, e.g.llvm-cov-18. If set to""the Rust code isn't instrumented, which turns off its coverage. This is independent ofcovr.gcov, which only controls C, C++ and Fortran code. -
covr.llvm_profdata: Path to thellvm-profdataused to merge the coverage counts of Rust code. Found likecovr.llvm_cov. -
covr.report_colors: A named character vector with the colors of covered and missed lines inreport()andfile_report(), and of the coverage percentages printed in the console, e.g.c(covered = "#0072B2", missed = "#D55E00"). colorblind_palette has colors that are easier to tell apart than the default green and red with color vision deficiency. Either element can be left out to keep its default. An optionalpartialelement sets the color of partial coverage (at least 75% but less than 90%), which otherwise followscovered, or is yellow in the console ifcoveredisn't set either, and of lines with a branch that wasn't taken in reports with branch coverage, which are otherwise yellow. Transparency is ignored. In terminals with only 8 colors, the console uses the closest of those colors. -
covr.rstudio_source_markers: A logical value. IfTRUE(the default behavior), source markers are displayed within the RStudio IDE when usingzero_coverage. -
covr.record_tests: IfTRUE(defaultFALSE), record a listing of top level test expressions and associate tests withcovrtraces evaluated during the test's execution. For more details, see?covr.record_tests. -
covr.full_traversal: IfTRUE(defaultFALSE), also trace functions nested inside lists and environments, such asfns <- list(a = function(x) x)or functions defined insidelocal(). This walks every object in the package, so it is off by default. Forpackage_coverage()it can also be enabled for a package by addingConfig/covr/full_traversal: trueto its DESCRIPTION; the option takes precedence when set. -
covr.install_instrument: IfFALSE(defaultTRUE),package_coverage()installs a package as usual and instruments it each time a process loads it, rather than once after installing it. Can also be set with the environment variableCOVR_INSTALL_INSTRUMENT.
Some options can also be set with an environment variable. They are read in
this order: the option, then the environment variable (ignored if it is
empty), then the default. So an option set in R always takes precedence over
the environment variable, e.g. COVR_FIX_PARALLEL_MCEXIT=false has no
effect if options(covr.fix_parallel_mcexit = TRUE) is set. Logical
settings are TRUE or FALSE, or for the environment variable (and
options set to a string), one of true, t, yes or 1, and false,
f, no or 0, in any case. Other values are ignored with a warning.
Author(s)
Maintainer: Jim Hester james.f.hester@gmail.com
Authors:
Jim Hester james.f.hester@gmail.com
Other contributors:
Willem Ligtenberg [contributor]
Kirill Müller [contributor]
Henrik Bengtsson [contributor]
Steve Peak [contributor]
Kirill Sevastyanenko [contributor]
Jon Clayden [contributor]
Robert Flight [contributor]
Eric Brown [contributor]
Brodie Gaslam [contributor]
Will Beasley [contributor]
Robert Krzyzanowski [contributor]
Markus Wamser [contributor]
Karl Forner [contributor]
Gergely Daróczi [contributor]
Jouni Helske [contributor]
Kun Ren [contributor]
Jeroen Ooms [contributor]
Ken Williams [contributor]
Chris Campbell [contributor]
David Hugh-Jones [contributor]
Qin Wang [contributor]
Doug Kelkhoff [contributor]
Ivan Sagalaev (highlight.js library) [contributor, copyright holder]
See Also
Useful links:
Report bugs at https://github.com/r-lib/covr/issues
Annotate source code with line and branch coverage
Description
Produces plain text showing source lines together with their coverage
counts, in a form that is easy to read in a terminal or to paste into a
prompt. By default the missed lines are shown with context surrounding
lines.
Usage
annotate_coverage(
x,
lines = NULL,
context = 2,
files = NULL,
max_lines = getOption("covr.annotate_max_lines", 200)
)
Arguments
x |
A coverage object, e.g. from |
lines |
A data frame with |
context |
Number of lines to show before and after each line in
|
files |
Optional character vector of file names (as they appear in the
coverage, e.g. |
max_lines |
The maximum number of source lines to show, 200 by default
(option |
Details
Each shown line has the line number, a count column and the source. Missed
lines are marked !!0, covered code lines show their hit count, and lines
without coverage data (blank lines, comments, ...) have an empty count.
Non-adjacent chunks are separated by ....
If branch coverage was measured (see covr.branch_coverage), lines with a
branch that was not taken are also shown by default, followed by
<- not taken: and the labels of their missed branches. Only if and
switch() calls that were evaluated count; the others are covered by the
missed lines. Such a line keeps
its count if it was run.
Value
A character vector of class covr_annotation, with one element per
output line. If there is nothing to show it is "No missed lines.".
Examples
source <- "
f <- function(x) {
if (x) {
'yes'
} else {
'no'
}
}
"
cov <- code_coverage(source, "f(TRUE)")
annotate_coverage(cov)
annotate_coverage(cov, context = Inf)
Convert a coverage object to a data frame
Description
Convert a coverage object to a data frame
Usage
## S3 method for class 'coverage'
as.data.frame(x, row.names = NULL, optional = FALSE, sort = TRUE, ...)
Arguments
x |
a coverage object. |
row.names, optional |
ignored, for compatibility with
|
sort |
if |
... |
ignored. |
Value
A data frame with one row for each traced expression of R code and each line of compiled code, and the columns:
-
filename: the source file, relative to therootattribute ofx(the package directory, forpackage_coverage()) if there is one. -
functions: the name of the function containing the expression, orNAfor compiled code. -
first_line,last_line: the lines the expression starts and ends on. -
first_byte,last_byte: the bytes of those lines the expression starts and ends at. -
first_column,last_column: the columns the expression starts and ends at. These differ from the bytes when the line contains multibyte characters. -
first_parsed,last_parsed: the lines as seen by the parser. These differ fromfirst_lineandlast_linewhen the source uses#linedirectives. -
value: the number of times the expression was executed.
Use tally_coverage() for one row for each line instead.
Examples
cov <- code_coverage("add <- function(x, y) { x + y }", "add(1, 2)")
as.data.frame(cov)
Create a coverage badge
Description
Write an SVG badge showing the percent coverage, in the style of the badges made by Codecov and shields.io, so a README can show the coverage of a package without uploading it to a coverage service. The badge is made locally and doesn't need a network connection.
Usage
badge(x, file = "coverage.svg", label = "coverage")
Arguments
x |
the coverage object returned from |
file |
the name of the SVG file |
label |
the text on the left side of the badge |
Details
The coverage is that of percent_coverage(), rounded down to a whole
percent so that only fully covered code shows 100%. The badge is green for
coverage of 90% or more, yellow for 75% or more and red below that, the
same thresholds used by report(). Coverage without any lines of code,
such as that of a package with no R code, shows as unknown on a gray
badge.
The badge is a plain file, so on a continuous integration service it needs
to be stored somewhere that the README can link to, e.g. committed to a
separate branch of the repository.
system.file("workflows", "test-coverage-badge.yaml", package = "covr") is
a GitHub Actions workflow that does this.
Value
The lines of the SVG file, invisibly, after writing them to
file.
Examples
cov <- code_coverage(
"f <- function(x) {\n y <- x + 1\n if (y > 0) {\n 'yes'\n } else {\n 'no'\n }\n}",
"f(1)"
)
tmp <- tempfile(fileext = ".svg")
badge(cov, tmp)
cat(readLines(tmp), sep = "\n")
Combine coverage objects
Description
Combine the coverage of several runs, e.g. of tests in different
directories, into a single coverage object. The counts of traces present in
more than one object are added, and traces only in some of the objects are
appended. Tests recorded with options(covr.record_tests = TRUE) are
combined as well.
Usage
## S3 method for class 'coverage'
c(...)
Arguments
... |
Coverage objects, e.g. from |
Details
The result keeps the attributes of the first object, such as the package
and root used for relative paths, except that the lines excluded from line
coverage are the union of the excluded lines of all objects. As with
package_coverage(type = c("tests", "examples")), the result only has a
type if all objects have the same type.
As with any S3 method for c(), this method is only used when the first
argument is a coverage object.
Value
A coverage object.
Examples
source_file <- tempfile(fileext = ".R")
writeLines(
c(
"add <- function(x, y) {",
" x + y",
"}",
"subtract <- function(x, y) {",
" x - y",
"}"
),
source_file
)
add_test <- tempfile(fileext = ".R")
writeLines("add(1, 2)", add_test)
subtract_test <- tempfile(fileext = ".R")
writeLines("subtract(2, 1)", subtract_test)
add_cov <- file_coverage(source_file, add_test)
subtract_cov <- file_coverage(source_file, subtract_test)
percent_coverage(add_cov)
percent_coverage(c(add_cov, subtract_cov))
Create a Cobertura XML file
Description
Create a
cobertura-compliant XML report following this DTD.
Because there are two DTDs called coverage-04.dtd and some tools do not seem to
adhere to either of them, the parser you're using may balk at the file. Please see
this github discussion for
context. Where covr doesn't provide a coverage metric (complexity), a zero
is reported.
Usage
cobertura(x, file = "cobertura.xml")
Arguments
x |
the coverage object returned from |
file |
the name of the Cobertura XML file |
Details
Branch rates are only reported if branches were measured with
options(covr.branch_coverage = TRUE) (see covr.branch_coverage),
otherwise they are zero. Each line where an if or switch() starts then
has branch="true" and a condition-coverage such as "50% (1/2)", the
percentage and number of the branches of the if and switch() calls on
the line that were taken. The branch rate of code without branches is one.
Note: This functionality requires the xml2 package be installed.
Value
The XML document (an xml2 document), invisibly, after
writing it to file.
Calculate coverage of code directly
Description
This function is useful for testing, and is a thin wrapper around
file_coverage() because parseData is not populated properly
unless the functions are defined in a file.
Usage
code_coverage(
source_code,
test_code,
line_exclusions = NULL,
function_exclusions = NULL,
...
)
Arguments
source_code |
A character vector of source code |
test_code |
A character vector of test code |
line_exclusions |
a named list of files with the lines to exclude from each file. |
function_exclusions |
a vector of regular expressions matching function
names to exclude. Example |
... |
Additional arguments passed to |
Value
A coverage object.
Parallel code
Code run in processes forked by parallel::mclapply(),
parallel::mcparallel() and related functions (not available on Windows)
is included in the coverage. While the code runs, parallel:::mcfork and
parallel:::mcexit are patched so that the forked processes save their
counts when they exit. To turn this off, set the option
covr.fix_parallel_mcexit or the environment variable
COVR_FIX_PARALLEL_MCEXIT to FALSE.
Examples
source <- "add <- function(x, y) { x + y }"
test <- "add(1, 2) == 3"
code_coverage(source, test)
Run covr on a package and upload the result to codecov.io
Description
Uploads coverage to Codecov with the current upload protocol, the one used
by the Codecov CLI and the
codecov/codecov-action GitHub Action. This takes two requests:
Usage
codecov(
...,
coverage = NULL,
base_url = "https://ingest.codecov.io",
token = NULL,
commit = NULL,
branch = NULL,
pr = NULL,
flags = NULL,
quiet = TRUE
)
Arguments
... |
arguments passed to |
coverage |
an existing coverage object to submit, if |
base_url |
the url coverage is uploaded to. The default is Codecov's
upload API; change it for Codecov Enterprise. The former default
|
token |
a codecov upload token, if
If there is no token, the upload is sent without one, see the section “Tokens”. |
commit |
explicitly set the commit this coverage result object
corresponds to. Is looked up from the service or locally if it is
|
branch |
explicitly set the branch this coverage result object
corresponds to, this is looked up from the service or locally if it is
|
pr |
explicitly set the pr this coverage result object corresponds to,
this is looked up from the service if it is |
flags |
A flag to use for this coverage upload see https://docs.codecov.com/docs/flags for details. |
quiet |
if |
Details
-
POST <base_url>/upload/<git service>/<owner>::::<repo>/upload-coverage(for a repository in nested groups,owner/group/repoisowner:::group::::repo) tells Codecov about the commit, branch, pull request and CI job. The response contains aurlfor the upload on Codecov and a pre-signed location to send the coverage report to. -
PUTsends the report, covr's JSON coverage format (processed by Codecov as anRreport), to that location. With branch coverage (see covr.branch_coverage), the report uses Codecov's generic JSON format instead, as theRformat only takes line hits. A line with branches then has the number of its branches taken and the number of branches, e.g."1/2", so Codecov shows it as partly covered unless all were taken.
If quiet is FALSE, the url of the upload on Codecov is printed after a
successful upload.
The commit, branch, pull request, job, build URL and repository are looked up
from the environment variables of the CI service, which is one of Jenkins,
Travis, CircleCI, Drone, AppVeyor, GitLab CI,
GitHub Actions or Google Cloud Build. Anywhere else, or for values the
service does not provide, they are looked up from the local git repository
in the working directory. The repository (owner/repo) and the git service
(github, gitlab, bitbucket, ...) come from the CI service when it
provides them, otherwise from the origin remote of the local git
repository, otherwise the git service is assumed to be github.
Value
The response of Codecov to the request for an upload, invisibly: a
list that includes url, the url of the upload on Codecov. If Codecov
rejects either request, codecov() throws an error of class
covr_codecov_error with the response of Codecov in its message, except
when Codecov is rate limiting requests (HTTP 429) or is unavailable (HTTP
5xx), when it gives a warning of class covr_codecov_warning and returns
NULL instead, so CI does not fail because of a transient Codecov problem.
Tokens
Codecov authenticates uploads with an upload token, passed in the
Authorization header. Both the token of a repository and an organization
(global) upload token, which is shared by all of an organization's
repositories, can be used. The token is looked up as described for token.
See https://docs.codecov.com/docs/codecov-tokens.
Without a token, Codecov only accepts uploads for public repositories, and
only for an unprotected branch, which is a branch name with an owner prefix
such as owner:branch. Pull requests from forks do not have access to the
token as a CI secret, so on GitHub Actions, when there is no token, branch
is NULL and the head repository of the pull request (the
pull_request.head.repo.full_name of the event in GITHUB_EVENT_PATH)
differs from GITHUB_REPOSITORY, codecov() uses the label of the head of
the pull request, owner:branch, as the branch name, as
codecov/codecov-action does. Pull requests from the same repository, other
CI services and uploads from other branches use the plain branch name, so
without a token Codecov rejects them unless the branch is already
unprotected.
Alternative
Instead of uploading from R, write the coverage to a file and upload it with
the codecov/codecov-action GitHub Action, or any other Codecov uploader.
lcov() has no dependencies and writes lcov.info, which the action
uploads without further configuration:
- name: Test coverage
run: covr::lcov(covr::package_coverage())
shell: Rscript {0}
- uses: codecov/codecov-action@v5
with:
token: ${{ secrets.CODECOV_TOKEN }}
cobertura() writes the Cobertura XML format, for which the xml2 package
is needed.
Examples
## Not run:
codecov(path = "test")
## End(Not run)
Colors for color vision deficiency
Description
colorblind_palette has colors for the covr.report_colors option that
are easier to tell apart with color vision deficiency than the default
green and red: blue for covered code, yellow for partial coverage and
vermillion for missed code, from the Okabe-Ito palette. They are used in
report(), file_report() and the coverage percentages printed in the
console.
Usage
colorblind_palette
Format
A named character vector with elements covered, partial and
missed.
Details
To set the colors in your .Rprofile without loading covr, copy the
values.
Examples
colorblind_palette
## Not run:
options(covr.report_colors = covr::colorblind_palette)
report()
## End(Not run)
Coverage objects
Description
package_coverage(), file_coverage(), code_coverage(),
function_coverage() and environment_coverage() return a coverage
object, which records how many times each part of the code was executed.
Working with coverage objects
Rather than using the list directly, you will usually want to:
Get a data frame with one row for each expression with
as.data.frame()(as.data.frame.coverage()), or one row for each line or function withtally_coverage().Get the overall percentage with
percent_coverage(), or the percentage for each file withcoverage_to_list().Find the lines or functions which were never run with
zero_coverage(), list them as ranges withprint(x, missing = TRUE), or show their source withannotate_coverage().Get the execution counts as a named numeric vector with
value().Browse the coverage with
report()orfile_report().
Structure
A coverage object is a named list with one element for each traced
expression of R code and each line of compiled code. Each element is a list
with:
-
value: the number of times the expression or line was executed. -
srcref: a srcref with its location. Itssrcfileattribute holds the name and lines of the source file. -
functions: the name of the function containing it, orNAfor compiled code. -
tests: only present withoptions(covr.record_tests = TRUE), see covr.record_tests.
The names of the elements are the base name of the file followed by the
eight numbers of the srcref, separated by :. For example
foo.R:10:3:12:4:3:4:10:12 is an expression from line 10 column 3 to line
12 column 4 of foo.R (see as.data.frame.coverage() for the meaning of
each number). The srcfile of the srcref, or the filename column of
as.data.frame(), gives the path of the file.
Coverage objects from package_coverage() also have the attributes
package (information about the package, such as its package name and
path), root (the directory file names are relative to, or NULL) and,
if clean = FALSE, library (the install_path).
With options(covr.record_tests = TRUE), coverage objects also have a
tests attribute with the test calls, see covr.record_tests.
With options(covr.branch_coverage = TRUE), coverage objects also have a
branches attribute with the branches of each if and switch(), see
covr.branch_coverage.
Examples
cov <- code_coverage("add <- function(x, y) { x + y }", "add(1, 2)")
cov
as.data.frame(cov)
names(cov)
cov[[1]]$value
Convert a coverage dataset to a list
Description
Convert a coverage dataset to a list
Usage
coverage_to_list(x = package_coverage())
Arguments
x |
a coverage dataset, defaults to running |
Value
A list with two components: filecoverage, a named numeric vector
with the percentage of lines covered in each file, and totalcoverage,
the percentage of lines covered in the whole package. Both are rounded to
two decimal places.
Convert a coverage dataset to a markdown table
Description
Creates a markdown table with the total coverage and the coverage of each
file, suitable for a GitHub Actions job summary or a pull request comment.
If base is given, the table also includes the coverage of base and the
change from it.
Usage
coverage_to_markdown(x = package_coverage(), base = NULL)
Arguments
x |
a coverage dataset, defaults to running |
base |
an optional coverage dataset to compare against, e.g. the coverage of the main branch. |
Value
A character vector of markdown lines, with class "covr_markdown".
Examples
cov <- code_coverage(
"add <- function(x, y) { x + y }",
"add(1, 2)"
)
coverage_to_markdown(cov)
## Not run:
# In a GitHub Actions step
md <- coverage_to_markdown(package_coverage())
cat(md, file = Sys.getenv("GITHUB_STEP_SUMMARY"), sep = "\n", append = TRUE)
## End(Not run)
Run covr on a package and upload the result to coveralls
Description
On GitHub Actions, use the official
Coveralls action instead of
this function: write the coverage with cobertura() and upload
cobertura.xml with coverallsapp/github-action@v2. See the README for an
example workflow. With branch coverage, upload the LCOV file written by
lcov() instead, as the action reads which branches were taken from it.
Usage
coveralls(
...,
coverage = NULL,
repo_token = env_var("COVERALLS_TOKEN", "COVERALLS_REPO_TOKEN"),
service_name = NULL,
quiet = TRUE
)
Arguments
... |
arguments passed to |
coverage |
an existing coverage object to submit, if |
repo_token |
The secret repo token for your repository, found on your
repository's page on Coveralls. The default is the environment variable
|
service_name |
The name of the CI service. If |
quiet |
if |
Details
With branch coverage (see covr.branch_coverage), each source file sent to
Coveralls also has its branches: the line, block, branch and count of
each branch, as in lcov(). A branch that was never taken has a count of
zero.
The CI service, job, pull request, branch and commit are detected from the
environment variables of the services codecov() supports. Anywhere else,
the branch, commit and remote are looked up from the local git repository.
The environment variables CI_BRANCH and CI_REMOTE override the detected
branch and remote.
Value
The response of Coveralls, parsed from JSON, invisibly. If Coveralls
doesn't accept the upload, coveralls() throws an error of class
covr_coveralls_error with the HTTP status and the response of Coveralls
in its message.
Deprecated functions
Description
These functions are deprecated and warn once per session (to_cobertura()
only in interactive sessions). They return the
same value as the functions that replace them, and cov and filename
are the x and file arguments of those functions:
-
to_cobertura()is nowcobertura(). -
to_sonarqube()is nowsonarqube().
Usage
to_cobertura(cov, filename = "cobertura.xml")
to_sonarqube(cov, filename = "sonarqube.xml", path_prefix = NULL)
Arguments
cov |
the coverage object returned from |
filename |
the name of the output file |
path_prefix |
SonarQube expects file paths relative to the project's
base directory. By default the paths are relative to the package root
(e.g. |
Branch coverage
Description
By setting options(covr.branch_coverage = TRUE) before measuring
coverage, covr also records which branches of each if and switch() in R
code were taken. Line and expression coverage are the same as without it.
Branch coverage is experimental: what counts as a branch, and how branches
are stored and reported, may change.
Details
The option is read when the code is instrumented, so it has no cost when it
is not set. When it is set, every if and switch() that runs calls a
function of covr, which makes the code slower.
Branches
An
ifhas two branches,"TRUE"and"FALSE". The"FALSE"branch of anifwithout anelseis taken when the condition isFALSE. Nothing is recorded if the condition isNAor otherwise signals an error.A
switch()has a branch for each of its arms, labelled with the name of the arm. Arms that fall through to the next arm (switch(x, a = , b = 1)) share its branch, labelled"a, b". An unnamed arm is labelled"<default>", or with its position if all arms are unnamed. Aswitch()without a default arm has another branch,"<no match>", taken when no arm matches, including a number that selects no arm. Aswitch()with arms in...has no branches.
&&, || and loops have no branches, nor does compiled code.
If the line where an if or switch() starts is excluded, e.g. with
# nocov (see exclusions), all its branches are excluded too.
Results
The branches are in the branches attribute of the coverage object, a list
with an element for each if and switch(), named like the elements of
the coverage object (see coverage). Each is a list with the srcref of
the if or switch(), its functions, the labels of its branches, and
value, the number of times each branch was taken. Use
tally_coverage(by = "branch") for a data frame with one row for each
branch, and percent_coverage(by = "branch") for the percentage of
branches taken.
report(), file_report(), lcov(), cobertura(), sonarqube(),
codecov() and coveralls() include the branches. The reports show the
number of branches taken on each line and the percentage of branches taken
in each file, and show a line with branches that weren't all taken as partly
covered. Codecov shows such lines as partly covered too, and counts them as
not covered in the coverage percentage, so the percentage on Codecov is
lower with branch coverage.
Examples
withr::with_options(list(covr.branch_coverage = TRUE), {
cov <- code_coverage(
"f <- function(x) {\n if (x > 0) 'positive'\n 'done'\n}",
"f(1)"
)
})
tally_coverage(cov, by = "branch")
percent_coverage(cov, by = "branch")
Record Test Traces During Coverage Execution
Description
By setting options(covr.record_tests = TRUE), the result of covr coverage
collection functions will include additional data pertaining to the tests
which are executed and an index of which tests, at what stack depth, trigger
the execution of each trace.
Details
This functionality requires that the package code and tests are installed and
sourced with the source. For more details, refer to R options, keep.source,
keep.source.pkgs and keep.parse.data.pkgs.
Additional fields
Within the covr result, you can explore this information in two places:
-
attr(,"tests"): A list of call stacks, which results in target code execution. -
$<srcref>$tests: For each srcref count in the coverage object, a$testsfield is now included which contains a matrix with four columns, "test", "call", "depth" and "i". "test" is the test number (corresponding to the index of the test inattr(,"tests")), "call" is the number of times the test expression was evaluated to produce the trace hit, "depth" is the stack depth into the target code where the trace was executed, and "i" is the order of execution for each test.
Test traces
The content of test traces are dependent on the unit testing framework that is used by the target package. The behavior is contingent on the available information in the sources kept for the testing files.
Test traces are extracted by the following criteria:
If any
srcreffiles are are provided by a file within covr's temporary library, all calls from those files are kept as a test trace. This will collect traces from tests run with common testing frameworks such astestthatandRUnit.Otherwise, as a conservative fallback in situations where no source references are found, or when none are from within the temporary directory, the entire call stack is collected.
These calls are subsequently subset for only those up until the call to
covr's internal count function, and will always include the last call in
the call stack prior to a call to count.
Functions in the recorded calls, such as the function of an R6 active
binding or a function passed to do.call(), have their environment replaced
with emptyenv(), so that the objects they enclose aren't saved with the
coverage.
To find which tests ran each line of code, use tally_tests().
Examples
fcode <- '
f <- function(x) {
if (x)
f(!x)
else
FALSE
}'
cov <- withr::with_options(
list(covr.record_tests = TRUE),
code_coverage(fcode, "f(TRUE)")
)
# extract executed test code for the first test
tail(attr(cov, "tests")[[1L]], 1L)
# [[1]]
# f(TRUE)
# extract test itemization per trace
cov[[3]][c("srcref", "tests")]
# $srcref
# f(!x)
#
# $tests
# test call depth i
# [1,] 1 1 2 4
# reconstruct the code path of a test by ordering test traces by [,"i"]
lapply(cov, `[[`, "tests")
# $`source.Ref2326138c55:4:6:4:10:6:10:4:4`
# test call depth i
# [1,] 1 1 1 2
#
# $`source.Ref2326138c55:3:8:3:8:8:8:3:3`
# test call depth i
# [1,] 1 1 1 1
# [2,] 1 1 2 3
#
# $`source.Ref2326138c55:6:6:6:10:6:10:6:6`
# test call depth i
# [1,] 1 1 2 4
Coverage measured so far in the current process
Description
current_coverage() returns the coverage that instrumented code has
recorded so far in the current R process. Call it from code that covr runs,
such as the code of package_coverage() or with_coverage(), to measure
the coverage of parts of a run, e.g. of each test file in turn.
Usage
current_coverage(reset = FALSE)
Arguments
reset |
If |
Details
Only the current process is included: code run in other processes, e.g. by
parallel::mclapply(), is added to the coverage that covr returns at the
end of the run, but not to that of current_coverage(). No exclusions are
applied.
Value
A coverage object, with no traces if no code was instrumented.
Examples
env <- new.env()
code <- "f <- function(x) {
if (x) {
'yes'
} else {
'no'
}
}"
eval(parse(text = code, keep.source = TRUE), env)
with_coverage(
{
env$f(TRUE)
first <- current_coverage(reset = TRUE)
env$f(FALSE)
second <- current_coverage()
},
env = env
)
tally_coverage(first)
tally_coverage(second)
The source file of each trace
Description
display_name() returns the path of the source file of each trace of a
coverage object, relative to the package root, e.g. to keep the coverage of
some files with x[display_name(x) %in% files].
Usage
display_name(x)
Arguments
x |
A coverage object. |
Value
A character vector with one path for each trace of x, or NULL
if x has no traces.
Examples
cov <- code_coverage("f <- function(x) x + 1", "f(1)")
display_name(cov)
Calculate coverage of an environment
Description
The functions in env are instrumented, then the files in test_files are
run with sys.source() in a child environment of env, from the current
working directory. Nothing else is set up, so testthat tests that rely on
its test runner, e.g. for setup files, snapshots, or the test directory as
the working directory (which testthat::test_path() uses to find fixtures
while testing), should instead be run with testthat::test_file() inside
with_coverage().
Usage
environment_coverage(
env = parent.frame(),
test_files,
line_exclusions = NULL,
function_exclusions = NULL
)
Arguments
env |
The environment to be instrumented. |
test_files |
Character vector of test files with code to test the functions |
line_exclusions |
a named list of files with the lines to exclude from each file. |
function_exclusions |
a vector of regular expressions matching function
names to exclude. Example |
Value
A coverage object.
Parallel code
Code run in processes forked by parallel::mclapply(),
parallel::mcparallel() and related functions (not available on Windows)
is included in the coverage. While the code runs, parallel:::mcfork and
parallel:::mcexit are patched so that the forked processes save their
counts when they exit. To turn this off, set the option
covr.fix_parallel_mcexit or the environment variable
COVR_FIX_PARALLEL_MCEXIT to FALSE.
Compiled code
environment_coverage() and with_coverage() include the compiled code in
the coverage of the namespace of a package loaded with pkgload::load_all()
(e.g. by devtools::load_all()), so devtools::test_coverage_active_file()
also works for files in src/. With compiled files in source_files,
file_coverage() loads their package with pkgload::load_all() and reports
the coverage of those files, without needing devtools:
file_coverage("src/foo.c", "tests/testthat/test-foo.R")
file_coverage("src/rust/src/lib.rs", "tests/testthat/test-foo.R")
The compiled code is measured in the current session, which is much faster
than package_coverage(): C, C++, Fortran and Objective-C code with gcov,
and Rust code (e.g. of packages using extendr or savvy) with LLVM's
source-based coverage, which needs the llvm tools described in
package_coverage(). An instrumented copy of the package is built in the
session's temporary directory, leaving the package's own build untouched,
and later runs only recompile the files that changed, with cargo's
incremental build in the copy's own target directory for Rust code.
While the code runs, the namespace's native routines use the instrumented
DLL instead of the package's own. Routines that were looked up some other
way, e.g. stored by .onLoad() or found by other packages with
R_GetCCallable(), keep using the package's DLL, so their code isn't
counted. Set options(covr.gcov = "") to leave out C, C++, Fortran and
Objective-C code, and options(covr.llvm_cov = "") to leave out Rust code.
See Also
Exclusions
Description
covr supports a couple of different ways of excluding some or all of a file.
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.
Function Exclusions
Alternatively function_exclusions can be used to exclude R functions
based on regular expression(s). For example print\\\.* can be used to
exclude all the print methods defined in a package from coverage.
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 or by specifying a range.
The patterns used can be specified by setting the global options
covr.exclude_pattern, covr.exclude_start, covr.exclude_end.
Examples
## Not run:
# exclude whole file of R/test.R
package_coverage(line_exclusions = list("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" = 1:10, "R/test2.R"))
# exclude all print and format methods from the package.
package_coverage(function_exclusions = c("print\\.", "format\\."))
# single line exclusions
f1 <- function(x) {
x + 1 # nocov
}
# ranged exclusions
f2 <- function(x) { # nocov start
x + 2
} # nocov end
## End(Not run)
Calculate test coverage for sets of files
Description
The files in source_files are first sourced into a new environment
to define functions to be checked. Then they are instrumented to track
coverage and the files in test_files are run with runner.
Usage
file_coverage(
source_files,
test_files,
line_exclusions = NULL,
function_exclusions = NULL,
parent_env = parent.frame(),
runner = source_test_file
)
Arguments
source_files |
Character vector of source files with function
definitions to measure coverage. Can also include compiled files from a
package's |
test_files |
Character vector of test files with code to test the functions |
line_exclusions |
a named list of files with the lines to exclude from each file. |
function_exclusions |
a vector of regular expressions matching function
names to exclude. Example |
parent_env |
The parent environment to use when sourcing the files.
If |
runner |
A function used to run each test file, called as
|
Value
A coverage object.
Parallel code
Code run in processes forked by parallel::mclapply(),
parallel::mcparallel() and related functions (not available on Windows)
is included in the coverage. While the code runs, parallel:::mcfork and
parallel:::mcexit are patched so that the forked processes save their
counts when they exit. To turn this off, set the option
covr.fix_parallel_mcexit or the environment variable
COVR_FIX_PARALLEL_MCEXIT to FALSE.
testthat tests
By default the test files are run with sys.source(), not with testthat's
test runner, so features that need the runner don't work. In particular,
testthat::expect_snapshot() is skipped ("Can't compare snapshot to
reference when testing interactively").
To use these features, run the test files with testthat::test_file():
file_coverage( "R/my_functions.R", "tests/test-my_functions.R", runner = testthat::test_file )
The tests then run in a child of the environment the source files were
sourced into, and snapshots are saved in a _snaps directory next to the
test file. expect_snapshot() also needs testthat's 3rd edition (e.g.
testthat::local_edition(3) in the tests), and is skipped unless the
NOT_CRAN environment variable is "true".
For more control, source the files yourself and use with_coverage().
Files from a package
To make the package's other functions available, load the package (e.g.
with pkgload::load_all()) and use parent_env = asNamespace("pkg").
Calls from other package files use the namespace's untraced functions, so
don't count. devtools::test_coverage_active_file() measures the coverage
of one file of a package without this limitation.
Compiled code
environment_coverage() and with_coverage() include the compiled code in
the coverage of the namespace of a package loaded with pkgload::load_all()
(e.g. by devtools::load_all()), so devtools::test_coverage_active_file()
also works for files in src/. With compiled files in source_files,
file_coverage() loads their package with pkgload::load_all() and reports
the coverage of those files, without needing devtools:
file_coverage("src/foo.c", "tests/testthat/test-foo.R")
file_coverage("src/rust/src/lib.rs", "tests/testthat/test-foo.R")
The compiled code is measured in the current session, which is much faster
than package_coverage(): C, C++, Fortran and Objective-C code with gcov,
and Rust code (e.g. of packages using extendr or savvy) with LLVM's
source-based coverage, which needs the llvm tools described in
package_coverage(). An instrumented copy of the package is built in the
session's temporary directory, leaving the package's own build untouched,
and later runs only recompile the files that changed, with cargo's
incremental build in the copy's own target directory for Rust code.
While the code runs, the namespace's native routines use the instrumented
DLL instead of the package's own. Routines that were looked up some other
way, e.g. stored by .onLoad() or found by other packages with
R_GetCCallable(), keep using the package's DLL, so their code isn't
counted. Set options(covr.gcov = "") to leave out C, C++, Fortran and
Objective-C code, and options(covr.llvm_cov = "") to leave out Rust code.
Examples
# Save code and tests to temporary files
source_file <- tempfile(fileext = ".R")
test_file <- tempfile(fileext = ".R")
cat("add <- function(x, y) { x + y }", file = source_file)
cat("add(1, 2) == 3", file = test_file)
# Use file_coverage() to calculate test coverage
file_coverage(source_files = source_file, test_files = test_file)
A coverage report for a specific file
Description
file_report() saves the coverage of one file as a standalone HTML file and
opens it. file_report_html() creates the same report as HTML that can be
included in a larger document, like report_html().
Usage
file_report(
x = package_coverage(),
file = NULL,
out_file = file.path(tempdir(), paste0(get_package_name(x), "-file-report.html")),
browse = interactive()
)
file_report_html(x = package_coverage(), file = NULL)
Arguments
x |
a coverage dataset, defaults to running |
file |
The file to report on, if |
out_file |
The output file |
browse |
whether to open a browser to view the report. |
Details
With branch coverage, the report shows the branches of the file as described
in the "Branches" section of report().
Value
file_report() returns the absolute path of the report file,
invisibly.
file_report_html() returns an htmltools::tagList(), with the
dependencies of the report attached.
Calculate test coverage for a specific function.
Description
Calculate test coverage for a specific function.
Usage
function_coverage(fun, code = NULL, env = NULL, enc = parent.frame())
Arguments
fun |
name of the function. |
code |
expressions to run. |
env |
environment the function is defined in. |
enc |
the enclosing environment which to run the expressions. |
Value
A coverage object.
Parallel code
Code run in processes forked by parallel::mclapply(),
parallel::mcparallel() and related functions (not available on Windows)
is included in the coverage. While the code runs, parallel:::mcfork and
parallel:::mcexit are patched so that the forked processes save their
counts when they exit. To turn this off, set the option
covr.fix_parallel_mcexit or the environment variable
COVR_FIX_PARALLEL_MCEXIT to FALSE.
Examples
add <- function(x, y) { x + y }
function_coverage(fun = add, code = NULL) # 0% coverage
function_coverage(fun = add, code = add(1, 2) == 3) # 100% coverage
Run covr on package and create report for GitLab
Description
Utilize internal GitLab static pages to publish package coverage. Creates local covr report in a package subdirectory. Uses the pages GitLab job to publish the report.
Usage
gitlab(..., coverage = NULL, file = "public/coverage.html", quiet = TRUE)
Arguments
... |
arguments passed to |
coverage |
an existing coverage object to submit, if |
file |
The path of the HTML report, relative to the root directory of the package (not the working directory). Directories that don't exist are created. |
quiet |
if |
Value
The path of the report, invisibly.
Determine if code is being run in covr
Description
covr functions set the environment variable R_COVR to "true" while they
are running. in_covr() returns TRUE if the environment variable is
exactly "true" and FALSE otherwise, e.g. to skip tests that don't work
while measuring coverage.
Usage
in_covr()
Value
A single TRUE or FALSE.
Examples
testthat::skip_if(in_covr())
Create an LCOV tracefile
Description
Write coverage in the LCOV tracefile format described in
geninfo(1),
which is read by genhtml, Codecov, Coveralls, SonarQube and editor
plugins such as Coverage Gutters.
Usage
lcov(x, file = "lcov.info")
Arguments
x |
the coverage object returned from |
file |
the name of the LCOV file |
Details
Each source file gets a record with its functions (FN, FNDA, FNF,
FNH) and lines (DA, LF, LH). Line counts are those of
tally_coverage() with by = "line", combined so that each source line
has a single DA record: when several functions share a line, the line's
count is the smallest of theirs, so a line only counts as covered if all its
code was run, as in report(), percent_coverage() and codecov(). A
function's count is the largest count of any of its expressions.
Branches are only recorded if they were measured with
options(covr.branch_coverage = TRUE) (see covr.branch_coverage). Each
branch gets a BRDA record on the line where its if or switch()
starts, numbered from zero within each if or switch(). Its count is -
if the if or switch() never ran. BRF and BRH give the number of
branches and the number of branches taken.
Source file paths (SF) are written as covr reports them, for a package
relative to the package root, so tools such as genhtml should be run from
that directory.
Value
The lines of the LCOV file, invisibly, after writing them to
file.
Examples
cov <- code_coverage(
"f <- function(x) {\n y <- x + 1\n y * 2\n}\ng <- function() 1",
"f(1)"
)
tmp <- tempfile(fileext = ".info")
lcov(cov, tmp)
cat(readLines(tmp), sep = "\n")
Calculate test coverage for a package
Description
This function calculates the test coverage for a development package on the
path. By default it runs only the package tests, but it can also run
vignette and example code.
Usage
package_coverage(
path = ".",
type = c("tests", "vignettes", "examples", "all", "none"),
combine_types = TRUE,
relative_path = TRUE,
quiet = TRUE,
clean = TRUE,
line_exclusions = NULL,
function_exclusions = NULL,
code = character(),
install_path = temp_file("R_LIBS"),
...,
allow_failures = getOption("covr.allow_failures", FALSE),
show_code_output = FALSE
)
Arguments
path |
file path to the package, or to an installed package. |
type |
run the package ‘tests’, ‘vignettes’, ‘examples’, ‘all’, or ‘none’. The default is ‘tests’. |
combine_types |
If |
relative_path |
whether to output the paths as relative or absolute paths. If a string, it is interpreted as a root path and all paths will be relative to that root. |
quiet |
whether to load and compile the package quietly, useful for debugging errors. |
clean |
whether to clean temporary output files after running, mainly
useful for debugging errors. If coverage fails, or failures are reported as
warnings with |
line_exclusions |
a named list of files with the lines to exclude from each file. |
function_exclusions |
a vector of regular expressions matching function
names to exclude. Example |
code |
A character vector of additional test code to run. |
install_path |
The path the instrumented package will be installed to
and tests run in. By default it is a path in the R sessions temporary
directory. It can sometimes be useful to set this (along with |
... |
Additional arguments passed to |
allow_failures |
If |
show_code_output |
If |
Details
This function uses tools::testInstalledPackage() to run the
code, if you would like to test your package in another way you can set
type = "none" and pass the code to run as a character vector to the
code parameter.
Coverage is also recorded in other R processes that load the package, such
as callr sessions, future or parallel cluster workers, or
Shiny apps run by shinytest2. Each process saves its coverage when it
exits normally, so the coverage is lost if a process is killed (e.g. with
SIGKILL or SIGTERM) or is still running when the tests finish, and
package_coverage() warns (with class covr_unsaved_trace). Stop these
processes gracefully and wait for them to exit, e.g. call $stop() on a
shinytest2 AppDriver, which waits longer for the app to exit when
run by covr. See vignette("shiny", package = "covr") for measuring the
coverage of Shiny apps.
path can also be an installed package, e.g.
system.file(package = "pkg"), to compute coverage without the package
source. The package must have been installed with its tests and source
references, e.g. with
remotes::install_github("user/pkg", INSTALL_opts = c("--install-tests", "--with-keep.source")). File names are those of the source it was
installed from, and compiled code isn't covered.
The coverage of Rust code, built by cargo into a static library that is
linked into the package, is measured with LLVM's source-based coverage.
This needs the llvm tools of the Rust toolchain
(rustup component add llvm-tools), or for Rust installed by a Linux
distribution, those of the LLVM version rustc uses (e.g.
apt-get install llvm-18); without them package_coverage()
warns and reports no coverage for the Rust code. covr instruments the
crates of the package's cargo workspace by having cargo run rustc through a
wrapper (with RUSTC_WORKSPACE_WRAPPER) that adds -C instrument-coverage,
so it works however the package sets RUSTFLAGS, and dependencies are
built as usual. Vendored crates, including the C code they compile, and
code generated in cargo's target directory aren't included. The code that
macros such as #[extendr] and #[savvy] generate is counted on the
macro's line, so the line isn't covered if parts of the generated code
never run, e.g. the handling of arguments that can't be converted. The
coverage of Rust code isn't measured on Windows, as rustup's Rust for the
x86_64-pc-windows-gnu target that Rtools uses has no profiler runtime.
Parallelized code using parallel's mcparallel() needs to
use a patched parallel:::mcexit. This is done automatically if the
package depends on parallel, but can also be explicitly set using the
global option covr.fix_parallel_mcexit or the environment variable
COVR_FIX_PARALLEL_MCEXIT.
Value
A coverage object. If combine_types = FALSE and more than one
type is run, a list of class coverages with one coverage object for
each type, named by type.
See Also
exclusions() For details on excluding parts of the
package from the coverage calculations.
Provide percent coverage of package
Description
Calculate the total percent coverage from a coverage result object.
Usage
percent_coverage(x, ...)
Arguments
x |
the coverage object returned from |
... |
additional arguments passed to |
Value
The total percentage as a numeric(1).
Print a coverage object
Description
Print a coverage object
Usage
## S3 method for class 'coverage'
print(
x,
group = c("filename", "functions"),
by = "line",
n = Inf,
missing = FALSE,
...
)
Arguments
x |
the coverage object to be printed |
group |
whether to group coverage by filename or function |
by |
whether to count coverage by line, expression or function |
n |
the maximum number of files or functions to print. They are sorted from least to most covered, so the least covered are shown first. |
missing |
whether to list the lines that were not run after each file
or function that has any, as ranges such as If branch coverage was measured (see covr.branch_coverage), the missed
branches of each file or function are also listed, as |
... |
additional arguments ignored |
Value
The coverage object (invisibly).
Branches
If branch coverage was measured (see covr.branch_coverage), the
percentage of branches taken is also shown after the overall coverage, e.g.
Coverage: 87.40% (branches 72.00%).
Examples
cov <- code_coverage(
"f <- function(x) x + 1; g <- function(x) x - 1; h <- function(x) 0",
"f(1)"
)
print(cov, group = "functions", n = 2)
cov <- code_coverage(
"f <- function(x) {\n if (x) {\n 1\n\n # no\n 2\n }\n}",
"f(FALSE)"
)
print(cov, missing = TRUE)
Display covr results using a standalone report
Description
report() saves the coverage report as a standalone HTML file and opens it.
To include the report in a larger document, such as an R Markdown or Quarto
document, use report_html() instead.
Usage
report(
x = package_coverage(),
file = file.path(tempdir(), paste0(get_package_name(x), "-report.html")),
browse = interactive()
)
Arguments
x |
a coverage dataset, defaults to running |
file |
The report filename. |
browse |
whether to open a browser to view the report. |
Value
report() returns the absolute path of the report file,
invisibly.
Branches
If branch coverage was measured with options(covr.branch_coverage = TRUE)
(see covr.branch_coverage), the report also shows the branches of each
if and switch(). The title has the percentage of branches taken after
the line coverage, and the list of files has a "Branches" column with the
percentage of the branches of each file that were taken. In the source, a
line with branches has the number of its branches taken out of the total,
e.g. 1/2; hovering over it or focusing it shows the label and count of
each branch. A line with a branch that wasn't taken is shown as partly
covered, unless its if or switch() never ran, which leaves it missed.
Colors
Covered lines are shown in green and missed lines in red. To use other
colors, set the covr.report_colors option to a named character vector of
R colors (anything accepted by grDevices::col2rgb(); transparency is
ignored) with elements covered, missed and/or partial. The colors are
used for the highlighted lines and the coverage bars in the file list;
partial is used for the bars of files with at least 75% but less than 90%
coverage, which otherwise follow covered, and for the partly covered lines
of reports with branches, which are otherwise yellow.
colorblind_palette has colors that are easier to tell apart with color vision deficiency:
options(covr.report_colors = covr::colorblind_palette)
Dark mode
The report uses a dark theme if the browser or operating system is set to prefer one. The moon (or sun) button at the top right switches between the light and dark themes; the browser remembers the choice for other reports until it is switched back.
Examples
## Not run:
x <- package_coverage()
report(x)
# Colors that are distinguishable with most kinds of color blindness
old <- options(covr.report_colors = colorblind_palette)
report(x)
options(old)
## End(Not run)
A coverage report to include in other documents
Description
report_html() creates the coverage report shown by report() as HTML that
can be included in a larger document, such as an R Markdown or Quarto
document or a page made with htmltools. Printing it in an R Markdown or
Quarto chunk includes the report in the document; printing it in the console
shows it in the viewer.
Usage
report_html(x = package_coverage())
Arguments
x |
a coverage dataset, defaults to running |
Details
The report takes the width of the element it is in, and its styles and scripts only apply to the report, so they don't change the rest of the document. A document can include several reports.
The colors and the dark theme can be changed as described in report().
Value
An htmltools::tagList(), with the dependencies of the report
attached.
Examples
## Not run:
# In an R Markdown or Quarto chunk
report_html(package_coverage())
# Save it with other content
htmltools::save_html(
htmltools::tagList(
htmltools::h1("Package review"),
report_html(package_coverage())
),
"review.html"
)
## End(Not run)
Calculate test coverage for a Shiny app
Description
Measures the coverage of the functions of a Shiny app that is not part of a
package, while code runs its tests, by default with
shinytest2::test_app(). This includes the code run by the app in the R
processes that shinytest2 starts to run it. For apps in a package, use
package_coverage() instead.
Usage
shiny_app_coverage(
app_dir = ".",
code = shinytest2::test_app(app_dir),
line_exclusions = NULL,
function_exclusions = NULL
)
Arguments
app_dir |
The directory of the Shiny app. |
code |
The code to run the app's tests, evaluated in the calling environment. |
line_exclusions |
a named list of files with the lines to exclude from each file. |
function_exclusions |
a vector of regular expressions matching function
names to exclude. Example |
Details
The functions defined by the app's files (app.R, ui.R, server.R,
global.R and the files in R/) are instrumented when Shiny loads them,
in this R process and in the R processes started while code runs. This
includes a server function that isn't assigned to a name, such as the one
in server.R or one defined inline, e.g. shinyApp(ui, function(input, output) ...). Code outside functions, such as building the UI, is not
counted, as in package_coverage().
This works by adding covr to the default packages of R processes started
while code runs (the R_DEFAULT_PACKAGES environment variable), and
relies on internal hooks of Shiny which may change in future versions.
An app process saves its coverage when it exits normally, so stop it
gracefully, e.g. with $stop() on a shinytest2 AppDriver, which
waits longer for the app to exit when run by covr. If an app process is
killed or is still running when code finishes, its coverage is lost and
shiny_app_coverage() warns (with class covr_unsaved_trace).
AppDriver$new() skips tests on CRAN unless the NOT_CRAN environment
variable is "true".
Value
A coverage object.
See Also
vignette("shiny", package = "covr")
Examples
## Not run:
Sys.setenv(NOT_CRAN = "true")
shiny_app_coverage("path/to/app")
## End(Not run)
Create a SonarQube Generic XML file
Description
Write coverage in the generic test data XML format read by SonarQube.
Usage
sonarqube(x, file = "sonarqube.xml", path_prefix = NULL)
Arguments
x |
the coverage object returned from |
file |
the name of the SonarQube Generic XML file |
path_prefix |
SonarQube expects file paths relative to the project's
base directory. By default the paths are relative to the package root
(e.g. |
Details
Every line with coverage is reported as a lineToCover with its lineNumber
and whether it is covered, including the lines of compiled code. Each line
is reported once: when several functions share a line, it is only covered if
all its code was run, as in report() and percent_coverage().
Branches are only reported if they were measured with
options(covr.branch_coverage = TRUE) (see covr.branch_coverage). A line
where an if or switch() starts then also has branchesToCover, the
number of branches of the if and switch() calls on the line, and
coveredBranches, how many of them were taken.
This functionality requires the xml2 package be installed.
Value
The XML document (an xml2 document), invisibly, after writing it
to file.
Author(s)
Talkdesk Inc.
Tally coverage by line, expression, function or branch
Description
Tally coverage by line, expression, function or branch
Usage
tally_coverage(x, by = c("line", "expression", "function", "branch"))
Arguments
x |
the coverage object returned from |
by |
whether to tally coverage by line, expression, function or branch |
Value
A data.frame. With by = "expression" it is the same as
as.data.frame.coverage(). With by = "line" it has one row for each
function on each line of code (excluding blank lines, comments and lines
with only punctuation such as }) and the columns filename,
functions, line and value, where value is the smallest execution
count of the expressions on that line, so a line only counts as covered
if all its expressions were run. An expression spanning several lines,
such as a loop, only counts for the lines that none of the expressions
inside it are on. percent_coverage(), report() and the other line
based outputs count each line once, with the smallest count of its
functions.
With by = "function" it has one row for each top level R function and
the columns filename, functions, first_line, last_line and
value, where first_line and last_line span the function's traced
code and value is the largest execution count of its expressions, so a
function counts as covered if any of its code was run. Compiled code has
no function names, so it is left out.
With by = "branch" it has one row for each branch measured with
options(covr.branch_coverage = TRUE) (see covr.branch_coverage), and
the columns filename, functions, line and column (where the if
or switch() starts), branch (the index of the branch in its if or
switch()), label and value, the number of times the branch was
taken. It has no rows if branch coverage wasn't measured.
Examples
cov <- code_coverage(
"f <- function(x) {\n if (x) 'yes' else 'no'\n}\ng <- function() 1",
"f(TRUE)"
)
tally_coverage(cov)
tally_coverage(cov, by = "expression")
tally_coverage(cov, by = "function")
Tally which tests ran each line
Description
Builds a traceability matrix from coverage recorded with
options(covr.record_tests = TRUE): which tests ran each line of code. Use
it to find the tests to rerun after changing some lines, or the tests
exercising a function.
Usage
tally_tests(x)
Arguments
x |
a coverage object computed with
|
Details
Lines are those of tally_coverage() with by = "line", so blank lines,
comments, lines with only punctuation and excluded lines are left out. A
test is a top level call in a test file that ran package code, such as an
expectation; see covr.record_tests.
Value
A data.frame with one row for each line and each test that ran
it, and the columns:
-
filename,functions,line: the line of code, as intally_coverage(). -
test_file,test_line: where the test call is. Forpackage_coverage(), test files are relative to the package directory, e.g.tests/testthat/test-foo.R.NAif the test has no source references. -
test: the description of the enclosingtest_that()orit()call, orNA. -
value: the number of times the test ran the line.
Examples
cov <- withr::with_options(
list(covr.record_tests = TRUE),
code_coverage(
"f <- function(x) {\n if (x) 'yes' else 'no'\n}",
"f(TRUE)\nf(FALSE)"
)
)
tests <- tally_tests(cov)
tests
# The tests that ran lines 1 to 2
unique(tests[tests$line %in% 1:2, c("test_file", "test_line")])
Retrieve the execution counts from a coverage object
Description
Retrieve the execution counts from a coverage object
Usage
value(x, ...)
Arguments
x |
a coverage object, or one of its elements. |
... |
additional arguments passed to methods. |
Value
For a coverage object, a named numeric vector with the number of
times each traced expression or line was executed, named like the
elements of x (see coverage). For a single element, its count.
Examples
cov <- code_coverage("add <- function(x, y) { x + y }", "add(1, 2)")
value(cov)
Calculate coverage of arbitrary code run against an environment
Description
with_coverage() instruments the functions in env, evaluates code, and
returns the coverage that code produced. Unlike environment_coverage(),
which sys.source()s a set of files, code can be any expression. This
makes it possible to measure coverage while running tests with a test runner
such as testthat::test_file(), without having to recreate the runner's
infrastructure (reporters, snapshot handling, test environment, ...).
Usage
with_coverage(
code,
env = parent.frame(),
line_exclusions = NULL,
function_exclusions = NULL
)
Arguments
code |
The code to evaluate while measuring coverage. It is evaluated
lazily, in the calling environment, after |
env |
The environment to be instrumented, e.g. a package namespace. |
line_exclusions |
a named list of files with the lines to exclude from each file. |
function_exclusions |
a vector of regular expressions matching function
names to exclude. Example |
Details
Functions are instrumented in place, so every existing reference to them,
including ones captured by an environment created by code (e.g. the child
environment of the namespace that testthat::test_file() evaluates tests
in), runs the instrumented version. The only requirement is that code must
not re-create the functions in env, e.g. when using
testthat::test_file() with package set the package must not be reloaded
(use load_package = "none"), as reloading would replace the instrumented
functions with fresh, uninstrumented ones.
The instrumentation is removed and the counters are cleared when
with_coverage() exits, even if code fails.
Value
A coverage object.
Parallel code
Code run in processes forked by parallel::mclapply(),
parallel::mcparallel() and related functions (not available on Windows)
is included in the coverage. While the code runs, parallel:::mcfork and
parallel:::mcexit are patched so that the forked processes save their
counts when they exit. To turn this off, set the option
covr.fix_parallel_mcexit or the environment variable
COVR_FIX_PARALLEL_MCEXIT to FALSE.
Compiled code
environment_coverage() and with_coverage() include the compiled code in
the coverage of the namespace of a package loaded with pkgload::load_all()
(e.g. by devtools::load_all()), so devtools::test_coverage_active_file()
also works for files in src/. With compiled files in source_files,
file_coverage() loads their package with pkgload::load_all() and reports
the coverage of those files, without needing devtools:
file_coverage("src/foo.c", "tests/testthat/test-foo.R")
file_coverage("src/rust/src/lib.rs", "tests/testthat/test-foo.R")
The compiled code is measured in the current session, which is much faster
than package_coverage(): C, C++, Fortran and Objective-C code with gcov,
and Rust code (e.g. of packages using extendr or savvy) with LLVM's
source-based coverage, which needs the llvm tools described in
package_coverage(). An instrumented copy of the package is built in the
session's temporary directory, leaving the package's own build untouched,
and later runs only recompile the files that changed, with cargo's
incremental build in the copy's own target directory for Rust code.
While the code runs, the namespace's native routines use the instrumented
DLL instead of the package's own. Routines that were looked up some other
way, e.g. stored by .onLoad() or found by other packages with
R_GetCCallable(), keep using the package's DLL, so their code isn't
counted. Set options(covr.gcov = "") to leave out C, C++, Fortran and
Objective-C code, and options(covr.llvm_cov = "") to leave out Rust code.
See Also
Examples
## Not run:
# With a package loaded by pkgload::load_all()
ns <- asNamespace("mypkg")
with_coverage(
testthat::test_file(
"tests/testthat/test-foo.R",
package = "mypkg",
load_package = "none"
),
env = ns
)
## End(Not run)
Provide locations of zero coverage
Description
When examining the test coverage of a package, it is useful to know if there are any locations where there is 0 test coverage.
Usage
zero_coverage(x, ...)
Arguments
x |
a coverage object returned |
... |
additional arguments passed to
|
Details
if used within RStudio this function outputs the results using the Marker API.
Value
A data.frame with coverage data where the coverage is 0.
Examples
cov <- code_coverage(
"f <- function(x) {\n if (x) 'yes' else 'no'\n}\ng <- function() 1",
"f(TRUE)"
)
zero_coverage(cov)
zero_coverage(cov, by = "function")