Wrapper for source based code coverage (-Z instrument-coverage, [rust-lang/rust#79121]).
cargo-llvm-cov requires nightly toolchain and llvm-tools-preview:
sh
rustup component add llvm-tools-preview --toolchain nightly
sh
cargo install cargo-llvm-cov --version 0.1.0-alpha.5
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.
You can download prebuilt binaries from the Release page. Prebuilt binaries are available for macOS, Linux (gnu and musl), and Windows.
You can install cargo-llvm-cov using Homebrew tap on macOS and Linux:
sh
brew install taiki-e/tap/cargo-llvm-cov
Click to show a complete list of options
```console $ 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:
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.
sh
cargo llvm-cov
With html report (the report will be generated to target/llvm-cov
directory):
sh
cargo llvm-cov --html
open target/llvm-cov/index.html
or
sh
cargo llvm-cov --open
With plain text report (if --output-path
is not specified, the report will be printed to stdout):
sh
cargo llvm-cov --text | less -R
With json report (if --output-path
is not specified, the report will be printed to stdout):
sh
cargo llvm-cov --json --output-path cov.json
With lcov report (if --output-path
is not specified, the report will be printed to stdout):
sh
cargo llvm-cov --lcov --output-path lcov.info
Here is an example of GitHub Actions workflow that uploads coverage to [Codecov].
```yaml name: Coverage
on: [pull_request, push]
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-x8664-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.CODECOVTOKEN }} # not required for public repos files: lcov.info failciif_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].
-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.See also the code-coverage-related issues reported in rust-lang/rust.
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.