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

或者使用 shell 脚本：

#!/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

Doctests 覆盖率

# 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

未包含 Doctests：

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

参考资料

• cargo-llvm-cov 文档
• LLVM 覆盖率映射
• Rust 的 Codecov
• coveralls-api crate