grcov

grcov collects and aggregates code coverage information for multiple source files. grcov processes .profraw and .gcda files which can be generated from llvm/clang or gcc. grcov also processes lcov files (for JS coverage), out files (for Go coverage), and JaCoCo files (for Java and Kotlin coverage). Linux, macOS and Windows are supported.

This is a project initiated by Mozilla to gather code coverage results on Firefox.

man grcov
How to get grcov
Usage
Auto-formatting
Build & Test
Minimum requirements
License

man grcov

Usage: grcov [OPTIONS] <PATHS>...

Arguments:
  <PATHS>...
          Sets the input paths to use

Options:
  -b, --binary-path <PATH>
          Sets the path to the compiled binary to be used

      --llvm-path <PATH>
          Sets the path to the LLVM bin directory

  -t, --output-types <OUTPUT TYPE>
          Comma separated list of custom output types:
          - *html* for a HTML coverage report;
          - *coveralls* for the Coveralls specific format;
          - *lcov* for the lcov INFO format;
          - *covdir* for the covdir recursive JSON format;
          - *coveralls+* for the Coveralls specific format with function information;
          - *ade* for the ActiveData-ETL specific format;
          - *files* to only return a list of files.
          - *markdown* for human easy read.
          - *cobertura* for output in cobertura format.
          - *cobertura-pretty* to pretty-print in cobertura format.


          [default: lcov]

  -o, --output-path <PATH>
          Specifies the output path. This is a file for a single output type and must be a folder
          for multiple output types

      --output-config-file <PATH>
          Specifies the output config file

  -s, --source-dir <DIRECTORY>
          Specifies the root directory of the source files

  -p, --prefix-dir <PATH>
          Specifies a prefix to remove from the paths (e.g. if grcov is run on a different machine
          than the one that generated the code coverage information)

      --ignore-not-existing
          Ignore source files that can't be found on the disk

      --ignore <PATH>
          Ignore files/directories specified as globs

      --keep-only <PATH>
          Keep only files/directories specified as globs

      --path-mapping <PATH>


      --branch
          Enables parsing branch coverage information

      --filter <FILTER>
          Filters out covered/uncovered files. Use 'covered' to only return covered files,
          'uncovered' to only return uncovered files

          [possible values: covered, uncovered]

      --llvm
          Speeds-up parsing, when the code coverage information is exclusively coming from a llvm
          build

      --token <TOKEN>
          Sets the repository token from Coveralls, required for the 'coveralls' and 'coveralls+'
          formats

      --commit-sha <COMMIT HASH>
          Sets the hash of the commit used to generate the code coverage data

      --service-name <SERVICE NAME>
          Sets the service name

      --service-number <SERVICE NUMBER>
          Sets the service number

      --service-job-id <SERVICE JOB ID>
          Sets the service job id

          [aliases: service-job-number]

      --service-pull-request <SERVICE PULL REQUEST>
          Sets the service pull request number

      --parallel
          Sets the build type to be parallel for 'coveralls' and 'coveralls+' formats

      --threads <NUMBER>


      --precision <NUMBER>
          Sets coverage decimal point precision on output reports

          [default: 2]

      --guess-directory-when-missing


      --vcs-branch <VCS BRANCH>
          Set the branch for coveralls report. Defaults to 'master'

          [default: master]

      --log <LOG>
          Set the file where to log (or stderr or stdout). Defaults to 'stderr'

          [default: stderr]

      --log-level <LEVEL>
          Set the log level

          [default: ERROR]
          [possible values: OFF, ERROR, WARN, INFO, DEBUG, TRACE]

      --excl-line <regex>
          Lines in covered files containing this marker will be excluded

      --excl-start <regex>
          Marks the beginning of an excluded section. The current line is part of this section

      --excl-stop <regex>
          Marks the end of an excluded section. The current line is part of this section

      --excl-br-line <regex>
          Lines in covered files containing this marker will be excluded from branch coverage

      --excl-br-start <regex>
          Marks the beginning of a section excluded from branch coverage. The current line is part
          of this section

      --excl-br-stop <regex>
          Marks the end of a section excluded from branch coverage. The current line is part of this
          section

      --no-demangle
          No symbol demangling

  -h, --help
          Print help (see a summary with '-h')

  -V, --version
          Print version

How to get grcov

Grcov can be downloaded from releases or, if you have Rust installed, you can run cargo install grcov.

Usage

Example: How to generate source-based coverage for a Rust project

Install the llvm-tools or llvm-tools component:
```
rustup component add llvm-tools
```
Ensure that the following environment variable is set up:
```
export RUSTFLAGS="-Cinstrument-coverage"
```
Build your code:

cargo build
Ensure each test runs gets its own profile information by defining the LLVM_PROFILE_FILE environment variable (%p will be replaced by the process ID, and %m by the binary signature):
```
export LLVM_PROFILE_FILE="your_name-%p-%m.profraw"
```
Run your tests:

cargo test

In the CWD, you will see a .profraw file has been generated. This contains the profiling information that grcov will parse, alongside with your binaries.

Note that gcov coverage using the -Zprofile flag is no longer supported in Rust (details here). Use source based coverage and the -Cinstrument-coverage flag instead.

Example: How to generate .gcda files for C/C++

Pass --coverage to clang or gcc (or for older gcc versions pass -ftest-coverage and -fprofile-arcs options (see gcc docs).

Generate a coverage report from coverage artifacts

Generate a html coverage report like this:

grcov . -s . --binary-path ./target/debug/ -t html --branch --ignore-not-existing -o ./target/debug/coverage/

N.B.: The --binary-path argument is only necessary for source-based coverage.

You can see the report in target/debug/coverage/index.html.

(or alternatively with -t lcov grcov will output a lcov compatible coverage report that you could then feed into lcov's genhtml command).

LCOV output

By passing -t lcov you could generate an lcov.info file and pass it to genhtml:

genhtml -o ./target/debug/coverage/ --show-details --highlight --ignore-errors source --legend ./target/debug/lcov.info

LCOV output should be used when uploading to Codecov, with the --branch argument for branch coverage support.

Coveralls output

Coverage can also be generated in coveralls format:

grcov . --binary-path ./target/debug/ -t coveralls -s . --token YOUR_COVERALLS_TOKEN > coveralls.json

grcov with Travis

Here is an example of .travis.yml file for source-based coverage:

language: rust

before_install:
  - curl -L https://github.com/mozilla/grcov/releases/latest/download/grcov-x86_64-unknown-linux-gnu.tar.bz2 | tar jxf -

matrix:
  include:
    - os: linux
      rust: stable

script:
    - rustup component add llvm-tools
    - export RUSTFLAGS="-Cinstrument-coverage"
    - cargo build --verbose
    - LLVM_PROFILE_FILE="your_name-%p-%m.profraw" cargo test --verbose
    - ./grcov . --binary-path ./target/debug/ -s . -t lcov --branch --ignore-not-existing --ignore "/*" -o lcov.info
    - bash <(curl -s https://codecov.io/bash) -f lcov.info

grcov with Gitlab

Here is an example .gitlab-ci.yml which will build your project, then collect coverage data in a format that Gitlab understands. It is assumed that you'll use an image which already has relevant tools installed, if that's not the case put the appropriate commands at the beginning of the script stanza.

build:
  variables:
    # Set an environment variable which causes LLVM to write coverage data to the specified location. This is arbitrary, but the path passed to grcov (the first argument) must contain these files or the coverage

Grcov

Install / Use

README