测试覆盖率工具（JaCoCo 与 coverage.py 与 SonarQube）

<!-- pom.xml: JaCoCo Maven 插件配置 -->
<plugin>
    <groupId>org.jacoco</groupId>
    <artifactId>jacoco-maven-plugin</artifactId>
    <version>0.8.12</version>
    <executions>
        <!-- 测试前注入探针,生成 exec 数据文件 -->
        <execution>
            <id>prepare-agent</id>
            <goals><goal>prepare-agent</goal></goals>
        </execution>
        <!-- 测试后生成 HTML/XML/CSV 报告 -->
        <execution>
            <id>report</id>
            <phase>test</phase>
            <goals><goal>report</goal></goals>
        </execution>
        <!-- 覆盖率规则检查,不达标则构建失败 -->
        <execution>
            <id>check</id>
            <goals><goal>check</goal></goals>
            <configuration>
                <rules>
                    <rule>
                        <element>BUNDLE</element>
                        <limits>
                            <!-- 行覆盖率阈值 80% -->
                            <limit><counter>LINE</counter><value>COVEREDRATIO</value><minimum>0.80</minimum></limit>
                            <!-- 分支覆盖率阈值 70% -->
                            <limit><counter>BRANCH</counter><value>COVEREDRATIO</value><minimum>0.70</minimum></limit>
                        </limits>
                    </rule>
                </rules>
            </configuration>
        </execution>
    </executions>
</plugin>

// build.gradle: JaCoCo Gradle 配置
plugins {
    id 'jacoco'
}

jacoco {
    toolVersion = "0.8.12"
}

test {
    // 测试完成后生成报告
    finalizedBy jacocoTestReport
    // 覆盖率规则检查
    finalizedBy jacocoTestCoverageVerification
}

jacocoTestReport {
    reports {
        xml.required = true   // SonarQube 读取 XML
        html.required = true  // 开发者阅读 HTML
        csv.required = false
    }
}

jacocoTestCoverageVerification {
    violationRules {
        rule {
            limit { counter = 'LINE'; minimum = 0.80 }
            limit { counter = 'BRANCH'; minimum = 0.70 }
        }
    }
}

# 安装 coverage.py 与 pytest 集成插件
pip install coverage pytest-cov

# 方式一: 直接使用 coverage 命令
coverage run -m pytest
coverage report -m     # 终端输出带未覆盖行号
coverage html          # 生成 htmlcov/ 目录

# 方式二: 通过 pytest-cov 集成(推荐)
pytest --cov=src --cov-report=html --cov-report=xml --cov-branch

# .coveragerc: coverage.py 配置
[run]
source = src                # 仅统计 src/ 目录下的代码
branch = True               # 启用分支覆盖率(默认仅行覆盖率)
parallel = True             # 多进程并发场景下分文件写入
concurrency = multiprocessing,thread

[report]
# 排除不影响业务逻辑的代码行
exclude_lines =
    pragma: no cover        # 显式跳过标记
    def __repr__            # 调试用方法
    raise NotImplementedError
    if __name__ == .__main__.:
    if TYPE_CHECKING:       # 类型检查专用分支

# 覆盖率门槛:低于 80% 命令退出码非零
fail_under = 80
show_missing = True         # 显示未覆盖行号
skip_covered = True         # 跳过 100% 覆盖的文件

[html]
directory = htmlcov         # HTML 报告输出目录

[xml]
output = coverage.xml       # XML 报告路径(SonarQube/Codecov 读取)

{
  "name": "Coverage Quality Gate",
  "conditions": [
    {
      "metric": "new_coverage",
      "operator": "LESS_THAN",
      "threshold": "80",
      "error": true
    },
    {
      "metric": "new_line_coverage",
      "operator": "LESS_THAN",
      "threshold": "80",
      "error": true
    },
    {
      "metric": "new_branch_coverage",
      "operator": "LESS_THAN",
      "threshold": "65",
      "error": true
    }
  ]
}

# Maven 项目集成 SonarScanner 示例
mvn clean verify sonar:sonar \
  -Dsonar.projectKey=my-project \
  -Dsonar.host.url=https://sonarqube.example.com \
  -Dsonar.token=$SONAR_TOKEN \
  -Dsonar.coverage.jacoco.xmlReportPaths=target/site/jacoco/jacoco.xml

# 安装
pip install diff-cover

# 生成全量覆盖率 XML 报告
pytest --cov=src --cov-report=xml --cov-branch

# 对比 main 分支,仅检查 PR 变更行的覆盖率
diff-cover coverage.xml \
  --compare-branch=origin/main \
  --html-report=diff_coverage.html \
  --markdown-report=diff_coverage.md \
  --fail-under=80

# 命令退出码非零表示增量覆盖率不达标,CI 据此阻塞 PR

# .github/workflows/coverage.yml
name: Coverage Check
on:
  pull_request:
    branches: [ main ]
jobs:
  incremental-coverage:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0   # 深克隆以获取完整 git history
      - name: Setup Python
        uses: actions/setup-python@v5
        with: { python-version: '3.12' }
      - name: Install deps
        run: pip install -r requirements.txt diff-cover pytest-cov
      - name: Run tests with coverage
        run: pytest --cov=src --cov-report=xml --cov-branch
      - name: Incremental coverage check
        run: |
          diff-cover coverage.xml \
            --compare-branch=origin/main \
            --fail-under=80 \
            --markdown-report=diff_coverage.md
      - name: Comment PR with diff coverage
        if: always()
        uses: marocchino/sticky-pull-request-comment@v2
        with:
          path: diff_coverage.md