cargo-llvm-cov
Wrapper for source based code coverage (-Z instrument-coverage, rust-lang/rust#79121).
Installation
Prerequisites
cargo-llvm-cov requires nightly toolchain and llvm-tools-preview:
From source
cargo-llvm-cov relies on unstable compiler flags so it requires a nightly
toolchain to be installed, though does not require nightly to be the default
toolchain or the one with which cargo-llvm-cov itself is executed. If the default
toolchain is one other than nightly, running cargo llvm-cov
will find and use
nightly anyway.
From prebuilt binaries
You can download prebuilt binaries from the Release page. Prebuilt binaries are available for macOS, Linux (gnu and musl), and Windows.
Via Homebrew
You can install cargo-llvm-cov using Homebrew tap on macOS and Linux:
Usage
$ cargo llvm-cov --help
cargo-llvm-cov
Wrapper for source based code coverage (-Z instrument-coverage).
Use -h for short descriptions and --help for more details.
USAGE:
cargo llvm-cov [OPTIONS] [-- <args>...]
ARGS:
<args>...
Arguments for the test binary
OPTIONS:
--json
Export coverage data in "json" format
If --output-path is not specified, the report will be printed to
stdout.
This internally calls `llvm-cov export -format=text`. See
<https://llvm.org/docs/CommandGuide/llvm-cov.html#llvm-cov-export>
for more.
--lcov
Export coverage data in "lcov" format.
If --output-path is not specified, the report will be printed to
stdout.
This internally calls `llvm-cov export -format=lcov`. See
<https://llvm.org/docs/CommandGuide/llvm-cov.html#llvm-cov-export>
for more.
--text
Generate coverage reports in “text” format.
If --output-path or --output-dir is not specified, the report will
be printed to stdout.
This internally calls `llvm-cov show -format=text`. See
<https://llvm.org/docs/CommandGuide/llvm-cov.html#llvm-cov-show> for
more.
--html
Generate coverage reports in "html" format. If --output-dir is not
specified, the report will be generated in `target/llvm-cov`
directory.
This internally calls `llvm-cov show -format=html`. See
<https://llvm.org/docs/CommandGuide/llvm-cov.html#llvm-cov-show> for
more.
--open
Generate coverage reports in "html" format and open them in a
browser after the operation.
See --html for more.
--summary-only
Export only summary information for each file in the coverage data.
This flag can only be used together with either --json or --lcov.
--output-path <PATH>
Specify a file to write coverage data into.
This flag can only be used together with --json, --lcov, or --text.
See --output-dir for --html and --open.
--output-dir <DIRECTORY>
Specify a directory to write coverage reports into (default to
`target/llvm-cov`).
This flag can only be used together with --text, --html, or --open.
See also --output-path.
--ignore-filename-regex <PATTERN>
Skip source code files with file paths that match the given regular
expression
--doctests
Including doc tests (unstable)
--no-run
Compile, but don't run tests (unstable)
--no-fail-fast
Run all tests regardless of failure
-p, --package <SPEC>...
Package to run tests for
--workspace
Test all packages in the workspace [aliases: all]
--exclude <SPEC>...
Exclude packages from the test
--release
Build artifacts in release mode, with optimizations
--features <FEATURES>...
Space or comma separated list of features to activate
--all-features
Activate all available features
--no-default-features
Do not activate the `default` feature
--target <TRIPLE>
Build for the target triple
When this option is used, coverage for proc-macro and build script
will not be displayed because cargo does not pass RUSTFLAGS to them.
--manifest-path <PATH>
Path to Cargo.toml
-v, --verbose
Use verbose output (-vv very verbose/build.rs output)
--color <WHEN>
Coloring [possible values: auto, always, never]
--frozen
Require Cargo.lock and cache are up to date
--locked
Require Cargo.lock is up to date
-Z <FLAG>...
Unstable (nightly-only) flags to Cargo
-h, --help
Prints help information
-V, --version
Prints version information
By default, only the summary is printed to stdout.
With html report (the report will be generated to target/llvm-cov
directory):
or
With plain text report (if --output-path
is not specified, the report will be printed to stdout):
|
With json report (if --output-path
is not specified, the report will be printed to stdout):
With lcov report (if --output-path
is not specified, the report will be printed to stdout):
Continuous Integration
Here is an example of GitHub Actions workflow that uploads coverage to Codecov.
name: Coverage
on:
jobs:
coverage:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- name: Install Rust
run: rustup toolchain install nightly --component llvm-tools-preview
- name: Install cargo-llvm-cov
run: curl -LsSf https://github.com/taiki-e/cargo-llvm-cov/releases/download/v0.1.0-alpha.5/cargo-llvm-cov-x86_64-unknown-linux-gnu.tar.gz | tar xzf - -C ~/.cargo/bin
- name: Generate code coverage
run: cargo llvm-cov --all-features --workspace --lcov --output-path lcov.info
- name: Upload coverage to Codecov
uses: codecov/codecov-action@v1
with:
token: ${{ secrets.CODECOV_TOKEN }} # not required for public repos
files: lcov.info
fail_ci_if_error: true
NOTE: Currently, only line coverage is available on Codecov. This is because -Z instrument-coverage
does not support branch coverage and Codecov does not support region coverage. See also #8, #12, and #20.
Known limitations
- Due to a bug of
-Z instrument-coverage
, some files may be ignored. There is a known workaround for this issue, but note that the workaround is likely to cause another problem. See rust-lang/rust#86177 and #26 for more. - Branch coverage is not supported yet. See #8 and rust-lang/rust#79649 for more.
- Support for doc tests is unstable and has known issues. See #2 and rust-lang/rust#79417 for more.
See also the code-coverage-related issues reported in rust-lang/rust.
License
Licensed under either of Apache License, Version 2.0 or MIT license at your option.
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.