cargo-llvm-cov

cargo-llvm-cov - LLVM によるコードカバレッジ

cargo-llvm-cov は、LLVM のインストルメンテーションベースのカバレッジを使用して、Rust の正確なコードカバレッジを提供します。複数の出力形式に対応し、CI プラットフォームとシームレスに連携します。

このスキルを使う場合

次の場合はこのスキルを使ってください…	次の場合は代わりに関連スキルを使ってください…
LLVM のインストルメンテーションを使って行カバレッジ／分岐カバレッジを測定する	テストを並列で高速に実行するだけの場合 — cargo-nextest を使ってください
HTML／lcov／codecov レポートを生成する	未使用の依存関係を監査する — cargo-machete を使ってください
CI でカバレッジのしきい値を適用する	lint ルールを設定する — clippy-advanced を使ってください
codecov.io または coveralls へのアップロードを設定する	テスト自体を作成する — rust-development を使ってください

インストール

# Install cargo-llvm-cov
cargo install cargo-llvm-cov

# Verify installation
cargo llvm-cov --version

# Install llvm-tools-preview component (required)
rustup component add llvm-tools-preview

基本的な使い方

# Run tests and generate coverage
cargo llvm-cov

# Generate HTML report
cargo llvm-cov --html
open target/llvm-cov/html/index.html

# Generate LCOV report
cargo llvm-cov --lcov --output-path target/llvm-cov/lcov.info

# Generate JSON report
cargo llvm-cov --json --output-path target/llvm-cov/coverage.json

# Show coverage as text summary
cargo llvm-cov --text

# Show coverage for specific files
cargo llvm-cov --text -- --show-instantiations

出力形式

# HTML report (interactive, line-by-line)
cargo llvm-cov --html --open

# LCOV format (compatible with many tools)
cargo llvm-cov --lcov --output-path lcov.info

# JSON format (programmatic analysis)
cargo llvm-cov --json --output-path coverage.json

# Cobertura XML (for Jenkins, GitLab)
cargo llvm-cov --cobertura --output-path cobertura.xml

# Text summary (terminal output)
cargo llvm-cov --text

# Multiple formats simultaneously
cargo llvm-cov --html --lcov --output-path lcov.info

CI でのカバレッジしきい値

# Fail if coverage is below threshold
cargo llvm-cov --fail-under-lines 80

# Multiple threshold types
cargo llvm-cov --fail-under-lines 80 --fail-under-functions 75

# Available threshold types
cargo llvm-cov --fail-under-lines 80      # Line coverage
cargo llvm-cov --fail-under-regions 80    # Region coverage
cargo llvm-cov --fail-under-functions 75  # Function coverage

しきい値の設定

しきい値を一貫して適用するためのスクリプトまたは Makefile を作成します。

# Makefile
.PHONY: coverage coverage-ci

coverage:
	cargo llvm-cov --html --open

coverage-ci:
	cargo llvm-cov \
		--fail-under-lines 80 \
		--fail-under-functions 75 \
		--lcov --output-path lcov.info

または、シェルスクリプトを使います。

#!/usr/bin/env bash
# scripts/coverage.sh
set -euo pipefail

COVERAGE_THRESHOLD="${COVERAGE_THRESHOLD:-80}"

cargo llvm-cov \
  --fail-under-lines "$COVERAGE_THRESHOLD" \
  --lcov --output-path target/llvm-cov/lcov.info \
  --html

echo "Coverage threshold: $COVERAGE_THRESHOLD% (lines)"

分岐カバレッジ（Nightly）

分岐カバレッジには Rust nightly が必要です。

# Install nightly toolchain
rustup toolchain install nightly
rustup component add llvm-tools-preview --toolchain nightly

# Run with branch coverage
cargo +nightly llvm-cov --branch --html

# Branch coverage with thresholds
cargo +nightly llvm-cov \
  --branch \
  --fail-under-lines 80 \
  --fail-under-branches 70

分岐カバレッジの設定

# rust-toolchain.toml
[toolchain]
channel = "nightly"
components = ["llvm-tools-preview"]

# Allows using `cargo llvm-cov --branch` without +nightly

cargo-nextest との連携

# Use nextest as test runner
cargo llvm-cov nextest --html

# With nextest profile
cargo llvm-cov nextest --profile ci --lcov --output-path lcov.info

# All nextest options work
cargo llvm-cov nextest -E 'not test(slow_)' --html

Codecov との連携

# .github/workflows/coverage.yml
name: Coverage

on: [push, pull_request]

jobs:
  coverage:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: dtolnay/rust-toolchain@stable
        with:
          components: llvm-tools-preview

      - name: Install cargo-llvm-cov
        uses: taiki-e/install-action@v2
        with:
          tool: cargo-llvm-cov

      - name: Generate coverage
        run: cargo llvm-cov --all-features --lcov --output-path lcov.info

      - name: Upload to codecov
        uses: codecov/codecov-action@v4
        with:
          files: lcov.info
          fail_ci_if_error: true
          token: ${{ secrets.CODECOV_TOKEN }}

Coveralls との連携

# .github/workflows/coverage.yml
name: Coverage

on: [push, pull_request]

jobs:
  coverage:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: dtolnay/rust-toolchain@stable
        with:
          components: llvm-tools-preview

      - name: Install cargo-llvm-cov
        uses: taiki-e/install-action@v2
        with:
          tool: cargo-llvm-cov

      - name: Generate coverage
        run: cargo llvm-cov --all-features --lcov --output-path lcov.info

      - name: Upload to Coveralls
        uses: coverallsapp/github-action@v2
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}
          path-to-lcov: lcov.info

高度な設定

カバレッジからファイルを除外する

# Exclude generated code
cargo llvm-cov --ignore-filename-regex '.*generated.*'

# Exclude test files
cargo llvm-cov --ignore-filename-regex '.*test.*'

# Multiple patterns
cargo llvm-cov \
  --ignore-filename-regex '.*generated.*' \
  --ignore-filename-regex '.*mock.*'

ワークスペースのカバレッジ

# Coverage for all workspace members
cargo llvm-cov --workspace --html

# Coverage for specific packages
cargo llvm-cov -p my_lib -p my_app --html

# Exclude specific packages
cargo llvm-cov --workspace --exclude integration_tests --html

フィーチャーフラグを使ったカバレッジ

# Coverage with all features
cargo llvm-cov --all-features --html

# Coverage with specific features
cargo llvm-cov --features async,tls --html

# Coverage without default features
cargo llvm-cov --no-default-features --html

GitHub Actions：完全な例

# .github/workflows/coverage.yml
name: Coverage

on:
  push:
    branches: [main]
  pull_request:

env:
  CARGO_TERM_COLOR: always
  COVERAGE_THRESHOLD: 80

jobs:
  coverage:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: dtolnay/rust-toolchain@stable
        with:
          components: llvm-tools-preview

      - uses: Swatinem/rust-cache@v2

      - name: Install cargo-llvm-cov
        uses: taiki-e/install-action@v2
        with:
          tool: cargo-llvm-cov

      - name: Install cargo-nextest
        uses: taiki-e/install-action@v2
        with:
          tool: nextest

      - name: Generate coverage
        run: |
          cargo llvm-cov nextest \
            --all-features \
            --fail-under-lines $COVERAGE_THRESHOLD \
            --lcov --output-path lcov.info \
            --html

      - name: Upload coverage to Codecov
        uses: codecov/codecov-action@v4
        with:
          files: lcov.info
          fail_ci_if_error: true
          token: ${{ secrets.CODECOV_TOKEN }}

      - name: Upload HTML report
        uses: actions/upload-artifact@v4
        if: always()
        with:
          name: coverage-report
          path: target/llvm-cov/html/

カバレッジデータをクリーンアップする

# Clean previous coverage data
cargo llvm-cov clean

# Clean and run fresh coverage
cargo llvm-cov clean && cargo llvm-cov --html

doctest のカバレッジ

# Include doctests in coverage
cargo llvm-cov --doc --html

# Doctests with workspace
cargo llvm-cov --workspace --doc --html

# Note: doctests run in separate context, may not integrate perfectly

tarpaulin との比較

機能	cargo-llvm-cov	cargo-tarpaulin
バックエンド	LLVM（コンパイラー）	ptrace（ランタイム）
精度	非常に高い	高い
パフォーマンス	高速	低速
分岐カバレッジ	対応（nightly）	対応
安定性	安定	不安定な場合あり
プラットフォーム対応	すべての Rust ターゲット	Linux、macOS は一部対応
セットアップの複雑さ	簡単	簡単

ベストプラクティス

1. 高速に実行するために nextest と併用する：

   cargo llvm-cov nextest --all-features --html
   

2. CI でカバレッジのしきい値を適用する：

   cargo llvm-cov --fail-under-lines 80
   

3. ツールごとに複数の形式を生成する：

   cargo llvm-cov --html --lcov --output-path lcov.info
   

4. 生成コードをカバレッジから除外する：

   cargo llvm-cov --ignore-filename-regex '.*generated.*'
   

5. CI でカバレッジの依存関係をキャッシュする：

   - uses: Swatinem/rust-cache@v2
   

6. 重要なコードには nightly で分岐カバレッジを使う：

   cargo +nightly llvm-cov --branch --fail-under-branches 70
   

7. 実行のたびにカバレッジデータをクリーンアップする：

   cargo llvm-cov clean
   

トラブルシューティング

llvm-tools-preview が見つからない場合：

rustup component add llvm-tools-preview

カバレッジが不正確に見える場合：

# Clean and regenerate
cargo llvm-cov clean
cargo clean
cargo llvm-cov --html

Nightly の機能が動作しない場合：

rustup toolchain install nightly
rustup component add llvm-tools-preview --toolchain nightly
cargo +nightly llvm-cov --branch --html

カバレッジの生成が遅い場合：

# Use nextest for parallel execution
cargo llvm-cov nextest --html

doctest が含まれない場合：

# Run with --doc flag
cargo llvm-cov --doc --html

参考資料

• cargo-llvm-cov のドキュメント
• LLVM coverage mapping
• Codecov Rust
• coveralls-api crate