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）： pom.xml に JaCoCo Maven プラグインを追加します：

<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 gem が必要です。

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>

または、公式アクションを使用します：

- 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
   

トラブルシューティング

よくある問題とその解決方法：

ステータス	原因	対処方法
コミットが見つかりません	Webhook が受信されていない、またはコミット SHA が間違っている	5～10 分待ち、コミット SHA が一致していることを確認します
保留中	レポート内のファイルパスがリポジトリの構造と一致しない	パスがリポジトリのルートからの相対パスであることを確認します（例：/home/ci/project/src/index.js ではなく src/index.js）
最終レポートが送信されません	final を指定せずに --partial を使用した	すべての部分アップロードの後に bash <(curl -Ls https://coverage.codacy.com/get.sh) final を追加します
ブランチが有効になっていません	解析されていないブランチのカバレッジをアップロードした	Codacy のリポジトリ設定でブランチを有効にします
PR にカバレッジが表示されません	共通の祖先コミットのカバレッジがない	PR だけでなく、すべてのブランチでカバレッジが実行されるようにします

重要な注意事項

• PR 分析で有効に活用するには、プッシュのたびにカバレッジをアップロードする必要があります。main だけでなく、すべてのブランチで実行されるように設定してください。
• PR のカバレッジ指標を取得するには、Codacy に PR のヘッドコミットとターゲットブランチとの共通祖先コミットの両方のカバレッジが必要です。
• カバレッジレポート内のファイルパスは、リポジトリルートからの相対パスにする必要があります。
• 複数の言語のカバレッジを取得するには、個別の -l <Language> フラグを使用するか、言語を指定して一部ずつアップロードする必要があります。