Coberturaカバレッジレポート

プラン: Free、Premium、Ultimate
提供形態: GitLab.com、GitLab Self-Managed、GitLab Dedicated

カバレッジ解析を機能させるには、適切にフォーマットされたCobertura XMLレポートをartifacts:reports:coverage_reportに提供する必要があります。この形式は元々Java用に開発されたものですが、他の言語やプラットフォームのほとんどのカバレッジ解析フレームワークには、それをサポートするプラグインがあります。次に例を示します:

simplecov-cobertura（Ruby）
gocover-cobertura（Go）
cobertura (Node.js)

その他のカバレッジ解析フレームワークは、追加設定なしでこの形式をサポートしています。次に例を示します:

Istanbul (JavaScript)
Coverage.py (Python)
PHPUnit (PHP)

設定後、マージリクエストがカバレッジレポートを収集するパイプラインをトリガーすると、カバレッジ情報が差分ビューに表示されます。これには、パイプライン内の任意のステージの任意のジョブからのレポートが含まれます。カバレッジは各行に次のように表示されます:

covered（緑）：テストで少なくとも1回チェックされた行
no test coverage（オレンジ）：読み込まれたものの、一度も実行されなかった行
カバレッジ情報なし：インストルメント化されていないか、読み込まれていない行

カバレッジバーにカーソルを合わせると、テストでその行がチェックされた回数など、詳細情報が表示されます。

テストカバレッジレポートをアップロードしても、以下は有効になりません:

マージリクエストウィジェットのテストカバレッジ結果。
コードカバレッジ履歴。

これらは個別に設定する必要があります。

制限

Cobertura形式のXMLファイルには、100個の<source>ノードの制限が適用されます。Coberturaレポートが100個のノードを超えると、マージリクエストの差分ビューで不一致が発生したり、一致しなくなる可能性があります。

単一のCobertura XMLファイルは、10 MiBを超えることはできません。大規模なプロジェクトの場合は、Cobertura XMLをより小さなファイルに分割します。詳細については、このイシューを参照してください。多数のファイルを送信すると、カバレッジがマージリクエストに表示されるまでに数分かかることがあります。

この視覚化は、パイプラインが完了した後にのみ表示されます。パイプラインにブロック手動ジョブがある場合、パイプラインは続行する前に手動ジョブを待機し、完了とはみなされません。ブロック手動ジョブが実行されなかった場合、視覚化を表示できません。

ジョブが複数のレポートを生成する場合は、アーティファクトパスでワイルドカードを使用します。

クラスパスの自動修正

カバレッジレポートが変更されたファイルを適切に照合するのは、filename``class要素にプロジェクトルートからの相対パスを含む完全なパスが含まれている場合に限ります。ただし、一部のカバレッジ解析フレームワークでは、生成されたCobertura XMLのfilenameパスには、代わりにクラスパッケージディレクトリからの相対パスが含まれています。

プロジェクトルートからの相対パスであるclassパスをインテリジェントに推測するために、Cobertura XMLパーサーは次の方法で完全なパスをビルドしようとします:

sources要素からsourceパスの一部を抽出し、クラスfilenameパスと組み合わせます。
候補パスがプロジェクトに存在するかどうかをチェックします。
一致する最初の候補をクラスの完全パスとして使用します。

パス修正の例

例として、次のC#プロジェクトを考えます:

完全パスがtest-org/test-cs-project。
プロジェクトルートからの相対パスである次のファイル:
```
Auth/User.cs
Lib/Utils/User.cs
```

Cobertura XMLからのsources。次の形式のパス<CI_BUILDS_DIR>/<PROJECT_FULL_PATH>/...:

<sources>
  <source>/builds/test-org/test-cs-project/Auth</source>
  <source>/builds/test-org/test-cs-project/Lib/Utils</source>
</sources>

パーサー:

AuthとLib/Utilsをsourcesから抽出し、これらを使用してプロジェクトルートからの相対パスであるclassパスを決定します。
これらの抽出されたsourcesとクラスのファイル名を組み合わせます。たとえば、filenameの値がUser.csのclass要素がある場合、パーサーは一致する最初の候補パス（Auth/User.cs）を取得します。
各class要素について、抽出されたsourceパスごとに最大100回の反復で一致するものを探そうとします。ファイルツリーに一致するパスが見つからないままこの制限に達すると、クラスは最終的なカバレッジレポートに含まれません。

クラスパスの自動修正は、次のJavaプロジェクトでも機能します:

完全パスがtest-org/test-java-project。
プロジェクトルートからの相対パスである次のファイル:
```
src/main/java/com/gitlab/security_products/tests/App.java
```

Cobertura XMLからのsources:

<sources>
  <source>/builds/test-org/test-java-project/src/main/java/</source>
</sources>

class要素（filenameの値がcom/gitlab/security_products/tests/App.java）:

<class name="com.gitlab.security_products.tests.App" filename="com/gitlab/security_products/tests/App.java" line-rate="0.0" branch-rate="0.0" complexity="6.0">

クラスパスの自動修正は、source形式の<CI_BUILDS_DIR>/<PROJECT_FULL_PATH>/...パスでのみ機能します。パスがこのパターンに従わない場合、sourceは無視されます。パーサーは、filename要素のclassにプロジェクトルートからの相対パスである完全なパスが含まれていると想定します。

テストカバレッジ設定の例

このセクションでは、さまざまなプログラミング言語のテストカバレッジ設定の例を示します。coverage-reportデモンストレーションプロジェクトで動作例を確認することもできます。

JavaScriptの例

次の.gitlab-ci.ymlの例では、Mocha JavaScriptテストとnycカバレッジツールを使用して、カバレッジアーティファクトを生成します:

test:
  script:
    - npm install
    - npx nyc --reporter cobertura mocha
  artifacts:
    reports:
      coverage_report:
        coverage_format: cobertura
        path: coverage/cobertura-coverage.xml

JavaとKotlinの例

GitLab 17.6以降は、JaCoCo形式をネイティブでサポートしています。新しいプロジェクトの場合は、ネイティブJaCoCoレポートを使用してください。

次の例では、jacoco2cobertura Dockerイメージを使用して、JaCoCoレポートをCobertura形式に変換します。

Mavenの例

test-jdk11ジョブは、Mavenを使用してJaCoCo XMLアーティファクトを生成します。coverage-jdk11ジョブは、それをCobertura形式に変換します:

test-jdk11:
  stage: test
  image: maven:3.6.3-jdk-11
  script:
    - mvn $MAVEN_CLI_OPTS clean org.jacoco:jacoco-maven-plugin:prepare-agent test jacoco:report
  artifacts:
    paths:
      - target/site/jacoco/jacoco.xml

coverage-jdk11:
  # The `visualize` stage does not exist by default
  # Define it first, or use an existing stage like `deploy`
  stage: visualize
  image: registry.gitlab.com/haynes/jacoco2cobertura:1.0.11
  script:
    # Convert report from JaCoCo to Cobertura, using relative project path
    - python /opt/cover2cover.py target/site/jacoco/jacoco.xml $CI_PROJECT_DIR/src/main/java/
        > target/site/cobertura.xml
  needs: ["test-jdk11"]
  artifacts:
    reports:
      coverage_report:
        coverage_format: cobertura
        path: target/site/cobertura.xml

Gradleの例

test-jdk11ジョブは、Gradleを使用してJaCoCo XMLアーティファクトを生成します。coverage-jdk11ジョブは、それをCobertura形式に変換します:

test-jdk11:
  stage: test
  image: gradle:6.6.1-jdk11
  script:
    - gradle test jacocoTestReport # JaCoCo must be configured to create an XML report
  artifacts:
    paths:
      - build/jacoco/jacoco.xml

coverage-jdk11:
  # The `visualize` stage does not exist by default
  # Define it first, or use an existing stage like `deploy`
  stage: visualize
  image: registry.gitlab.com/haynes/jacoco2cobertura:1.0.11
  script:
    # Convert report from JaCoCo to Cobertura, using relative project path
    - python /opt/cover2cover.py build/jacoco/jacoco.xml $CI_PROJECT_DIR/src/main/java/
        > build/cobertura.xml
  needs: ["test-jdk11"]
  artifacts:
    reports:
      coverage_report:
        coverage_format: cobertura
        path: build/cobertura.xml

Pythonの例

次の.gitlab-ci.ymlの例では、pytest-covを使用してテストカバレッジデータを収集します:

run tests:
  stage: test
  image: python:3
  script:
    - pip install pytest pytest-cov
    - pytest --cov --cov-report term --cov-report xml:coverage.xml
  artifacts:
    reports:
      coverage_report:
        coverage_format: cobertura
        path: coverage.xml

PHPの例

PHPの次の.gitlab-ci.yml例では、PHPUnitを使用してテストカバレッジデータを収集し、レポートを生成します。

最小限のphpunit.xmlファイルを使用すると（このレポートの例を参照）、テストを実行してcoverage.xmlを生成できます:

run tests:
  stage: test
  image: php:latest
  variables:
    XDEBUG_MODE: coverage
  before_script:
    - apt-get update && apt-get -yq install git unzip zip libzip-dev zlib1g-dev
    - docker-php-ext-install zip
    - pecl install xdebug && docker-php-ext-enable xdebug
    - php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');"
    - php composer-setup.php --install-dir=/usr/local/bin --filename=composer
    - composer install
    - composer require --dev phpunit/phpunit phpunit/php-code-coverage
  script:
    - php ./vendor/bin/phpunit --coverage-text --coverage-cobertura=coverage.cobertura.xml
  artifacts:
    reports:
      coverage_report:
        coverage_format: cobertura
        path: coverage.cobertura.xml

Codeceptionは、PHPUnitを介して、runでCoberturaレポートの生成もサポートしています。生成されるファイルのパスは、--coverage-coberturaオプションと、pathsの設定（単体テストスイート）によって異なります。.gitlab-ci.ymlを設定して、適切なパスでCoberturaを見つけます。

C/C++の例

コンパイラとしてgccまたはg++を使用したC/C++の次の.gitlab-ci.yml例では、gcovrを使用して、Cobertura XML形式でカバレッジ出力ファイルを生成します。

この例では、以下を前提としています。

Makefileが、前のステージの別のジョブで、buildディレクトリ内のcmakeによって作成されていること。(automakeを使用してMakefileを生成する場合は、make testの代わりにmake checkを呼び出す必要があります。)
cmake（またはautomake）がコンパイラオプション--coverageを設定していること。

run tests:
  stage: test
  script:
    - cd build
    - make test
    - gcovr --xml-pretty --exclude-unreachable-branches --print-summary -o coverage.xml --root ${CI_PROJECT_DIR}
  artifacts:
    name: ${CI_JOB_NAME}-${CI_COMMIT_REF_NAME}-${CI_COMMIT_SHA}
    expire_in: 2 days
    reports:
      coverage_report:
        coverage_format: cobertura
        path: build/coverage.xml

Goの例

Goの次の.gitlab-ci.yml例では、次のものを使用します:

テストを実行するためのgo test。
GoのカバレッジプロファイルをCobertura XML形式に変換するためのgocover-cobertura。

この例では、Goモジュールが使用されていることを前提としています。-covermode countオプションは、-raceフラグでは機能しません。-raceフラグを使用しながらコードカバレッジを生成する場合は、-covermode atomicに切り替える必要があります。これは-covermode countよりも低速です。詳細については、このブログ投稿を参照してください。

run tests:
  stage: test
  image: golang:1.17
  script:
    - go install
    - go test ./... -coverprofile=coverage.txt -covermode count
    - go get github.com/boumenot/gocover-cobertura
    - go run github.com/boumenot/gocover-cobertura < coverage.txt > coverage.xml
  artifacts:
    reports:
      coverage_report:
        coverage_format: cobertura
        path: coverage.xml

Rubyの例

Rubyの次の.gitlab-ci.yml例では、以下を使用します。

テストを実行するためのrspec。
カバレッジプロファイルを記録し、Cobertura XML形式でレポートを作成するためのsimplecovとsimplecov-cobertura。

この例では、以下を前提としています。

bundlerが、依存関係管理に使用されていること。rspec、simplecov、およびsimplecov-cobertura gemがGemfileに追加されていること。
CoberturaFormatterが、spec_helper.rbファイルのSimpleCov.formatters設定に追加されていること。

run tests:
  stage: test
  image: ruby:3.1
  script:
    - bundle install
    - bundle exec rspec
  artifacts:
    reports:
      coverage_report:
        coverage_format: cobertura
        path: coverage/coverage.xml

トラブルシューティング

テストカバレッジの視覚化が表示されない

テストカバレッジの視覚化が差分ビューに表示されない場合は、カバレッジレポート自体をチェックして、以下を確認できます:

差分ビューで表示しているファイルが、カバレッジレポートに記載されていること。
レポート内のsourceノードとfilenameノードが、予想される構造に従って、リポジトリ内のファイルと一致すること。
パイプラインが完了していること。パイプラインが手動ジョブでブロックされている場合、パイプラインは完了とはみなされません。
カバレッジレポートファイルが制限を超えていないこと。

レポートアーティファクトは、デフォルトではダウンロードできません。ジョブの詳細ページからレポートをダウンロードできるようにする場合は、アーティファクトのpathsにカバレッジレポートを追加します:

artifacts:
  paths:
    - coverage/cobertura-coverage.xml
  reports:
    coverage_report:
      coverage_format: cobertura
      path: coverage/cobertura-coverage.xml