README.md

grcov Action

This GitHub Action collects and aggregates code coverage data with the grcov tool.

Example workflow

on: [push]

name: Code Coverage

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v1
      - uses: actions-rs/toolchain@v1
        with:
          toolchain: nightly
          override: true
      - uses: actions-rs/cargo@v1
        with:
          command: test
          args: --all-features --no-fail-fast
        env:
          CARGO_INCREMENTAL: '0'
          RUSTFLAGS: '-Zprofile -Ccodegen-units=1 -Cinline-threshold=0 -Clink-dead-code -Coverflow-checks=off -Cpanic=abort -Zpanic_abort_tests'
          RUSTDOCFLAGS: '-Zprofile -Ccodegen-units=1 -Cinline-threshold=0 -Clink-dead-code -Coverflow-checks=off -Cpanic=abort -Zpanic_abort_tests'
      - uses: actions-rs/[email protected]

Usage

1. As grcov works with coverage data generated by the unstable -Z profile feature, you need to install nightly toolchain, for example, with the actions-rs/toolchain Action:

   - uses: actions-rs/toolchain@v1
     with:
       toolchain: nightly
       override: true

2. It is strongly recommended to call cargo clean command if any of cargo check, cargo build, cargo test or other similar commands were executed already in this workspace.

   - uses: actions-rs/cargo@v1
     with:
       command: clean

3. Create a configuration file for grcov, see config section for details.

4. Execute the cargo test command. It is required to add CARGO_INCREMENTAL, RUSTFLAGS and RUSTDOCFLAGS environment variables for this command, see grcov page for details.

   - uses: actions-rs/cargo@v1
     with:
       command: test
       args: --all-features --no-fail-fast  # Customize args for your own needs
     env:
       CARGO_INCREMENTAL: '0'
       RUSTFLAGS: '-Zprofile -Ccodegen-units=1 -Cinline-threshold=0 -Clink-dead-code -Coverflow-checks=off -Cpanic=abort -Zpanic_abort_tests'
       RUSTDOCFLAGS: '-Zprofile -Ccodegen-units=1 -Cinline-threshold=0 -Clink-dead-code -Coverflow-checks=off -Cpanic=abort -Zpanic_abort_tests'

   Note that -Clink-dead-code flag might be broken for macOS environments, see #63047

5. Add the actions-rs@grcov Action to the workflow.

   - id: coverage  
     uses: actions-rs/[email protected]

6. After the successful execution, actions-rs@grcov will set an Action output called report with an absolute path to the coverage report file.

   This file can be uploaded to any code coverage service, ex. with codecov or coveralls Actions help:

   - name: Coveralls upload
     uses: coverallsapp/github-action@master
     with:
       github-token: ${{ secrets.GITHUB_TOKEN }}
       path-to-lcov: ${{ steps.coverage.outputs.report }}

Inputs

• config: Configuration file path (relative to repository root, default to .github/actions-rs/grcov.yml)

Outputs

• report: Absolute path to the report file

Config

grcov execution can be tuned with the configuration file.
By default this Action tries to load it from the .github/actions-rs/grcov.yml path (relative to the repository root directory); you can change file location with the config input, ex.

- uses: actions-rs/[email protected]
  with:
    config: configs/grcov.yml

If configuration file is missing, default values will be used by the grcov.

All possible keys in the config are optional and directly mapped to the grcov flags and options.
Note that not all parameters can be changed via this file, see example below for config file format and available options.

Example

branch: true
ignore-not-existing: true
llvm: true
filter: covered
output-type: lcov
output-path: ./lcov.info
prefix-dir: /home/user/build/
ignore:
  - "/*"
  - "C:/*"
  - "../*"
path-mapping:
  - "/path1"
  - "/path2"

Notes

1. Coveralls Action is expecting LCOV format, do not use the coveralls or coveralls+ output type for the grcov.
   Instead, set the output-type config value to lcov.

2. Generated report file is stored in the temporary directory by default, which might not be accessible by the Docker-based Actions, such as codecov.
   Consider either mount it as a Docker volume or use the output-path option in the config to store report in the path accessible by container.