setup-coverage

配置覆盖率

术语表： 有关 Codacy 概念（问题、发现项、严重性、覆盖率、工具、模式等）的通用定义，请参阅 glossary.md。

此技能可在代码仓库中配置测试覆盖率报告，并设置自动上传到 Codacy。它会检测现有配置、找出缺失项并补齐。

前提条件

• 上传覆盖率时，必须能够使用 CODACY_PROJECT_TOKEN 或 CODACY_API_TOKEN（参阅身份验证）
• 代码仓库必须已添加到 Codacy

工作流

Coverage Setup Progress:
- [ ] Step 1: Detect testing setup
- [ ] Step 2: Detect CI/CD pipeline
- [ ] Step 3: Identify coverage gaps
- [ ] Step 4: Add coverage generation
- [ ] Step 5: Add Codacy coverage upload
- [ ] Step 6: Verify the setup

第 1 步：检测测试配置

扫描代码仓库，识别：

• 使用的语言（检查文件扩展名、构建文件、包清单）
• 测试框架（查找测试目录、测试文件和框架配置）：
  • JavaScript/TypeScript：Jest、Vitest、Mocha、NYC/Istanbul、c8
  • Python：pytest、unittest、coverage.py
  • Java：JUnit、JaCoCo、Maven Surefire/Failsafe
  • Kotlin：JUnit、JaCoCo（Gradle 或 Maven）
  • Android：JUnit、JaCoCo、Espresso、createDebugCoverageReport
  • Go：原生 go test
  • Ruby：RSpec、SimpleCov、Minitest
  • C#/.NET：xUnit、NUnit、MSTest、Coverlet、dotCover
  • Scala：sbt-jacoco、scoverage
  • PHP：PHPUnit
  • Swift/Obj-C：XCTest、Xcode Code Coverage
• 现有覆盖率配置（NYC 配置、Jest collectCoverage、pytest.ini 覆盖率设置、pom.xml/build.gradle 中的 JaCoCo 插件等）
• 现有覆盖率报告（查找 coverage/、lcov.info、cobertura.xml、jacoco*.xml 等）

继续操作前，先向用户报告发现的情况。

第 2 步：检测 CI/CD 流水线

识别正在使用的 CI/CD 系统：

CI/CD	检测文件
GitHub Actions	.github/workflows/*.yml
GitLab CI	.gitlab-ci.yml
CircleCI	.circleci/config.yml
Travis CI	.travis.yml
Bitbucket Pipelines	bitbucket-pipelines.yml
Jenkins	Jenkinsfile
Azure DevOps	azure-pipelines.yml

阅读 CI 配置，了解：

• 哪个步骤运行测试
• 是否已生成覆盖率报告
• 是否已有覆盖率上传步骤
• 配置了哪些环境变量或密钥

第 3 步：找出覆盖率配置缺口

根据第 1 步和第 2 步，确定缺少什么：

1. 完全没有测试——告知用户需要先添加测试。可以提出搭建测试框架骨架，但要说明必须编写实际测试。
2. 有测试但未生成覆盖率报告——需要添加覆盖率工具（第 4 步）。
3. 已生成覆盖率报告但未上传到 Codacy——需要添加上传步骤（第 5 步）。
4. 已生成并上传覆盖率报告，但未正常工作——参照故障排查部分进行排查。

向用户说明缺口分析结果，并在进行更改前确认计划。

第 4 步：添加覆盖率报告生成配置

添加生成 Codacy 支持格式的覆盖率报告所需的最简配置。根据语言和所用工具选择格式。完整的格式参考请参阅 references/coverage-formats.md。

特定语言的设置

JavaScript/TypeScript（Jest）：

// In package.json or jest.config.js
{
  "collectCoverage": true,
  "coverageReporters": ["lcov"]
}

或者运行：npx jest --coverage --coverageReporters=lcov

JavaScript/TypeScript（Vitest）：

// vitest.config.ts
{ test: { coverage: { reporter: ['lcov'] } } }

Python（pytest + coverage.py）：

pip install pytest-cov
pytest --cov --cov-report=xml:cobertura.xml

Java（Maven + JaCoCo）： 将 JaCoCo Maven 插件添加到 pom.xml：

<plugin>
  <groupId>org.jacoco</groupId>
  <artifactId>jacoco-maven-plugin</artifactId>
  <version>0.8.12</version>
  <executions>
    <execution>
      <goals><goal>prepare-agent</goal></goals>
    </execution>
    <execution>
      <id>report</id>
      <phase>test</phase>
      <goals><goal>report</goal></goals>
    </execution>
  </executions>
</plugin>

Java（Gradle + JaCoCo）：

plugins { id 'jacoco' }
jacocoTestReport { dependsOn test }

运行：./gradlew test jacocoTestReport

Kotlin（Gradle + JaCoCo）：

plugins { id 'jacoco' }
jacocoTestReport {
    dependsOn test
    reports { xml.required = true }
}

运行：./gradlew test jacocoTestReport

报告位置：build/reports/jacoco/test/jacocoTestReport.xml

Kotlin（Maven + JaCoCo）： 与上述 Java Maven + JaCoCo 设置相同——JaCoCo 原生支持 Kotlin 字节码。

Android（Gradle + JaCoCo）：

android {
    buildTypes {
        debug { testCoverageEnabled true }
    }
}

运行：./gradlew createDebugCoverageReport

报告位置：app/build/reports/coverage/debug/report.xml

对于多模块 Android 项目，请使用合并报告或分批上传（参见 references/coverage-upload.md）。

Go：

go test -coverprofile=coverage.out ./...

Ruby（SimpleCov）：

# At the top of spec/spec_helper.rb or test/test_helper.rb
require 'simplecov'
SimpleCov.start
SimpleCov.formatter = SimpleCov::Formatter::CoberturaFormatter

需要 simplecov 和 simplecov-cobertura gems。

C#/.NET（Coverlet）：

dotnet test --collect:"XPlat Code Coverage" -- DataCollectionRunSettings.DataCollectors.DataCollector.Configuration.Format=cobertura

Scala（sbt-jacoco）： 添加到 project/plugins.sbt：

addSbtPlugin("com.github.sbt" % "sbt-jacoco" % "3.5.0")

运行：sbt jacoco

PHP（PHPUnit）：

phpunit --coverage-clover clover.xml

步骤 5：添加 Codacy 覆盖率上传

在 CI/CD 流水线中，测试/覆盖率步骤之后添加覆盖率上传步骤。

身份验证

上传需要以下其中一种方式：

选项 A — 仓库令牌（单个仓库，更简单）：

• 将 CODACY_PROJECT_TOKEN 设置为 CI/CD 密钥
• 获取位置：Codacy > Repository Settings > Coverage > Repository API Token

选项 B — 账户令牌（多个仓库）：

• 设置以下 CI/CD 密钥：
  • CODACY_API_TOKEN — 从 Codacy > My Account > Access Management 获取
  • CODACY_ORGANIZATION_PROVIDER — gh、gl 或 bb
  • CODACY_USERNAME — 组织或用户名
  • CODACY_PROJECT_NAME — 仓库名称

务必提醒用户将相应的令牌添加为 CI/CD 密钥。

上传命令

标准上传命令：

bash <(curl -Ls https://coverage.codacy.com/get.sh) report -r <coverage-report-file>

对于 Go 覆盖率，添加解析器标志：

bash <(curl -Ls https://coverage.codacy.com/get.sh) report \
  --force-coverage-parser go -r coverage.out

对于多个报告（例如，单体仓库或多模块项目）：

bash <(curl -Ls https://coverage.codacy.com/get.sh) report \
  -r report1.xml -r report2.xml

或者使用分批上传：

bash <(curl -Ls https://coverage.codacy.com/get.sh) report --partial -r report1.xml
bash <(curl -Ls https://coverage.codacy.com/get.sh) report --partial -r report2.xml
bash <(curl -Ls https://coverage.codacy.com/get.sh) final

特定 CI/CD 平台的集成

GitHub Actions：

- name: Upload coverage to Codacy
  env:
    CODACY_PROJECT_TOKEN: ${{ secrets.CODACY_PROJECT_TOKEN }}
  run: bash <(curl -Ls https://coverage.codacy.com/get.sh) report -r <report-file>

或者使用官方 action：

- name: Upload coverage to Codacy
  uses: codacy/codacy-coverage-reporter-action@v1
  with:
    project-token: ${{ secrets.CODACY_PROJECT_TOKEN }}
    coverage-reports: <report-file>

GitLab CI：

upload-coverage:
  stage: test
  script:
    - bash <(curl -Ls https://coverage.codacy.com/get.sh) report -r <report-file>
  variables:
    CODACY_PROJECT_TOKEN: $CODACY_PROJECT_TOKEN

CircleCI（使用 orb）：

orbs:
  codacy: codacy/coverage-reporter@13
workflows:
  main:
    jobs:
      - test
      - codacy/upload_coverage:
          requires: [test]

Travis CI：

after_success:
  - bash <(curl -Ls https://coverage.codacy.com/get.sh) report -r <report-file>

Bitbucket Pipelines：

- step:
    name: Upload coverage
    script:
      - bash <(curl -Ls https://coverage.codacy.com/get.sh) report -r <report-file>

Alpine Linux（无 bash）：

wget -qO - https://coverage.codacy.com/get.sh | sh -s -- report -r <report-file>

高级上传场景请参见 references/coverage-upload.md。

步骤 6：验证设置

完成更改后：

1. 确认 CI 配置有效 — 检查 YAML 语法错误和逻辑问题
2. 列出用户需要手动执行的操作：
   • 将 CODACY_PROJECT_TOKEN（或账户令牌变量）添加为 CI/CD 密钥
   • 推送更改以触发 CI 运行
   • 流水线完成后，在 Codacy 中检查覆盖率数据
3. 提供验证清单：

   After pushing, verify:
   - [ ] CI pipeline passes (tests run, coverage report generated)
   - [ ] Coverage upload step succeeds (no errors in CI logs)
   - [ ] Codacy shows coverage data for the commit
   

故障排除

常见问题及其解决方法：

状态	原因	修复方法
Commit Not Found	未收到 webhook 或提交 SHA 错误	等待 5-10 分钟；确认提交 SHA 匹配
Pending	报告中的文件路径与仓库结构不匹配	确保路径相对于仓库根目录（例如，src/index.js，而非 /home/ci/project/src/index.js）
Final Report Not Sent	使用了 --partial，但没有使用 final	在所有分批上传之后添加 bash <(curl -Ls https://coverage.codacy.com/get.sh) final
Branch Not Enabled	为未分析的分支上传了覆盖率	在 Codacy 仓库设置中启用该分支
No coverage shown on PRs	缺少共同祖先提交的覆盖率	确保所有分支都会运行覆盖率，而不仅是 PR

重要说明

• 必须在每次推送时上传覆盖率数据，PR 分析才有用——请将其配置为在所有分支上运行，而不仅限于 main
• 要获取 PR 覆盖率指标，Codacy 需要 PR 头部提交和与目标分支的共同祖先提交的覆盖率数据
• 覆盖率报告中的文件路径必须相对于仓库根目录
• 多种语言的覆盖率需要分别使用 -l <Language> 标志，或指定语言进行部分上传