JUnitテストレポート
GitLab 11.2で導入されました。GitLab Runner 11.2以降が必要です。
概要
CI/CDパイプラインにコードを検証するテストジョブが含まれていることは非常によくあることです。テストが失敗するとパイプラインが失敗したことがユーザーに通知されます。マージリクエストの作業をしている人はジョブのログをチェックし、どこでテストが失敗したかを確認して修正しなければなりません。
JUnitのテストレポートを使用するようにジョブを設定すると、GitLabのマージリクエストにレポートが表示されるので、ログ全体をチェックしなくても簡単かつ迅速に障害を特定できます。
マージリクエストを使用せずに、ジョブのログを検索せずにJUnitの出力を見たい場合は、パイプラインの詳細ビューでJUnitのテストレポートをすべて見ることができます。
ユースケース
次のようなワークフローを考えてみましょう。
- プロジェクトはGitLab CI/CDを使用していて、
master
ブランチは信頼でき、パイプラインは正常に動作していることを示しています。 - チームの誰かがマージリクエストを作成して、そのテストが失敗すると、パイプラインには赤いアイコンが表示されます。詳細を調べるには、ジョブのログを調べてテストが失敗した原因を突き止める必要があります。しかし、ログは何千行にもなる場合があります。
- JUnitのテストレポートを設定すると、GitLabのマージリクエストに収集されたテスト結果がすぐに表示されます。これにより、ジョブのログを検索する手間を削減できます。
- 開発とデバッグのワークフローがより簡単に、より速く、より効率的になります。
どのように動作するか
まず、GitLab Runnerは、すべてのJUnit XMLファイルをアーティファクトとしてGitLabにアップロードします。 次に、マージリクエストにアクセスすると、GitLabはheadブランチとベースブランチのJUnitテストレポートの比較を開始します。
- ベースブランチとは、マージリクエストのターゲットブランチ(通常
master
)のことです。 - headブランチとは、マージリクエストのソースブランチのことです。
レポートパネルには、失敗したテストの数、エラーの数、修正されたテストの数を示すサマリーがあります。ベースブランチのデータが利用できず比較ができない場合は、パネルにはheadブランチで失敗したテストのリストが表示されます。
表示される結果は4つに分類されます。
- 新しく失敗したテスト: ベースブランチでは成功し、headブランチでは失敗したテストケース
- 新たに発生したエラー: ベースブランチでは成功し、headブランチではエラーにより失敗したテストケース
- 元から発生していた失敗: ベースブランチとheadブランチの両方で失敗したテストケース
- 解決された失敗: ベースブランチで失敗し、headブランチで成功したテストケース
パネル内の各エントリには、上のリストからテスト名とそのタイプが表示されます。テスト名をクリックすると、実行時間とエラー出力の詳細が表示されるモーダルウィンドウが開きます。
設定方法
マージリクエストでJUnitのレポートを有効にするには、artifacts:reports:junit
を.gitlab-ci.yml
に追加し、生成されたテストレポートのパスを指定する必要があります。レポートはxml
ファイルでなければなりません。そうしないとGitLabはエラー500を返します。
以下の例では、テスト
ステージでジョブが実行され、GitLabが各ジョブからJUnitのテストレポートを収集します。 各ジョブが実行された後、XMLレポートはアーティファクトとしてGitLabに保存され、その結果がマージリクエストウィジェットに表示されます。
artifacts:paths
キーワードを一緒に使用してください。その例をRubyの例として以下に示します。Rubyの例
.gitlab-ci.yml
で以下のジョブを使用します。これにはartifacts:paths
キーワードが含まれており、JUnit出力ファイルへのリンクを提供します。
## Use https://github.com/sj26/rspec_junit_formatter to generate a JUnit report with rspec
ruby:
stage: test
script:
- bundle install
- bundle exec rspec --format progress --format RspecJunitFormatter --out rspec.xml
artifacts:
paths:
- rspec.xml
reports:
junit: rspec.xml
Goの例
.gitlab-ci.yml
で次のようなジョブを使用し、-set-exit-code
を使用するようにします。
## Use https://github.com/jstemmer/go-junit-report to generate a JUnit report with go
golang:
stage: test
script:
- go get -u github.com/jstemmer/go-junit-report
- go test -v 2>&1 | go-junit-report -set-exit-code > report.xml
artifacts:
reports:
junit: report.xml
Javaの例
Javaには、JUnitレポートを作成できるツールがいくつかあります。
Gradle
以下の例では、テスト・レポートの生成にgradle
を使用しています。複数のテスト・タスクが定義されている場合、gradle
はbuild/test-results/
の下に複数のディレクトリを生成します。この場合、パスbuild/test-results/test/**/TEST-*.xml.
のようにglob形式でファイルパスを指定してください。
java:
stage: test
script:
- gradle test
artifacts:
reports:
junit: build/test-results/test/**/TEST-*.xml
Maven
SurefireおよびFailsafeのテストレポートを解析するには、.gitlab-ci.yml
で次のようなジョブを定義してください。
java:
stage: test
script:
- mvn verify
artifacts:
reports:
junit:
- target/surefire-reports/TEST-*.xml
- target/failsafe-reports/TEST-*.xml
Python example
以下の例では、pytestで--junitxml=report.xml
フラグを指定して、JUnitのフォーマットで出力しています。
pytest:
stage: test
script:
- pytest --junitxml=report.xml
artifacts:
reports:
junit: report.xml
C/C++の例
C/C++でJUnitレポートを作成できるツールがいくつかあります。
GoogleTest
異なるアーキテクチャ(x86
、x64
、arm
)用に作成された複数のgtest
実行ファイルがある場合は、そのファイル名を指定して各々テストを実行する必要があります。テスト結果は一緒に集計されます。
cpp:
stage: test
script:
- gtest.exe --gtest_output="xml:report.xml"
artifacts:
reports:
junit: report.xml
CUnit
CUnitは、CUnitCI.h
マクロを使用して実行すると、自動的にJUnit XMLレポートを作成できます。
cunit:
stage: test
script:
- ./my-cunit-test
artifacts:
reports:
junit: ./my-cunit-test.xml
.NETの例
JunitXML.TestLoggerNuGetパッケージは、.Net Frameworkと.Net Coreアプリケーション用のテストレポートを生成できます。以下の例では、リポジトリのルートフォルダにソリューションがあり、サブフォルダに1つ以上のプロジェクトファイルがあることを想定しています。テストプロジェクトごとに1つの結果ファイルが生成され、各ファイルは新しいアーティファクトフォルダに配置されます。この例には、オプションの書式設定引数が含まれており、テストウィジェット内のテストデータの可読性を向上させます。完全な.Net Coreのサンプルが用意されています。
## Source code and documentation are here: https://github.com/spekt/junit.testlogger/
Test:
stage: test
script:
- 'dotnet test --test-adapter-path:. --logger:"junit;LogFilePath=..\artifacts\{assembly}-test-result.xml;MethodFormat=Class;FailureBodyFormat=Verbose"'
artifacts:
when: always
paths:
- ./**/*test-result.xml
reports:
junit:
- ./**/*test-result.xml
GitLabでJUnitのテストレポートを表示する
JUnit XMLファイルを生成してパイプラインの一部としてアップロードした場合は、パイプラインの詳細ページでレポートを確認できます。このページのTestsタブには、XMLファイルから報告されたテストスイートとケースの一覧が表示されます。
既知のすべてのテストスイートを表示し、それぞれをクリックすると、そのスイートを構成するケースを含む詳細を見ることができます。ケースはステータス順に表示され、失敗したケースが一番上に表示され、次にスキップされたケース、成功したケースが最後に表示されます。
また、GitLab API経由でレポートを取得できます。
JUnit テストレポート機能を有効にする
この機能はフィーチャーフラグ:junit_pipeline_view
で設定され、デフォルトでは無効になっています。この機能は、非常に大きなデータセットでのパフォーマンスの問題があるため、無効になっています。パフォーマンスが改善された場合、この機能はデフォルトで有効になります。
この機能を有効にするには、Railsのコンソールへのアクセス権を持つGitLab管理者に以下のコマンドを実行してもらいます。
Feature.enable(:junit_pipeline_view)
# Enable the feature for a specific project
Feature.enable(:junit_pipeline_view, Project.find(<your-project-id-here>))
GitLabでJUnitのスクリーンショットを表示する
JUnit XMLファイルにattachment
タグが含まれている場合は、GitLabが添付ファイルを解析します。
スクリーンショットをアーティファクトとしてGitLabにアップロードします。attachment
タグには、アップロードしたスクリーンショットの絶対パスを指定しなければなりません。
<testcase time="1.00" name="Test">
<system-out>[[ATTACHMENT|/absolute/path/to/some/file]]</system-out>
</testcase>
この課題が完了すると、添付ファイルがパイプラインの詳細ページに表示されます。
JUnitのスクリーンショット機能を有効にする
この機能はフィーチャーフラグ:junit_pipeline_screenshots_view
で設定され、デフォルトでは無効になっています。
この機能を有効にするには、Railsのコンソールへのアクセス権を持つGitLab管理者に以下のコマンドを実行してもらいます。
Feature.enable(:junit_pipeline_screenshots_view)