ユニットテストレポート
CI/CD パイプラインにコードを検証するテストジョブが含まれていることはよくあります。テストが失敗すると、パイプラインは失敗し、ユーザーに通知されます。マージリクエストを担当する人は、ジョブのログをチェックしてテストが失敗した箇所を確認し、修正できるようにしなければなりません。
ジョブをユニットテストレポートを使うように設定すると、GitLab はマージリクエストにレポートを表示します。ユニットテストレポートは現在、JUnit レポート形式のテストレポートのみをサポートしています。
マージリクエストを使用しない場合でも、ジョブログを検索せずにユニットテストレポートの出力を見たい場合は、パイプラインの詳細ビューで完全なユニットテストレポートを利用できます。
次のようなワークフローを考えてみましょう。
- デフォルトブランチは強固で、プロジェクトは GitLab CI/CD を使っていて、パイプラインは何も壊れていないことを示しています。
- チームの誰かがマージリクエストを作成して、そのテストが失敗すると、パイプラインには赤いアイコンが表示されます。詳細を調べるには、ジョブのログを調べてテストが失敗した原因を突き止める必要があります。しかし、ログは何千行にもなる場合があります。
- ユニットテストレポートを設定すると、すぐにGitLabはそれらをマージリクエストに集めて公開します。もうジョブログを探す必要はありません。
- 開発とデバッグのワークフローがより簡単に、より速く、より効率的になります。
どのように動作するか
まず、GitLab RunnerはすべてのJUnitレポートフォーマットXMLファイルを アーティファクトとしてGitLabにアップロードします。そして、マージリクエストにアクセスすると、GitLab はヘッドブランチとベースブランチの JUnit レポートフォーマット XML ファイルの比較を開始します：
- ベースブランチはターゲットブランチ（通常はデフォルトブランチ）。
- headブランチとは、マージリクエストのソースブランチのことです。
テストサマリパネルには、どれだけのテストが失敗し、どれだけのエラーが発生し、どれだけのテストが修正されたかが表示されます。ベースブランチのデータがないために比較できない場合は、ソースブランチの失敗したテストのリストのみが表示されます。
結果の種類は次のとおりです：
- 新たに失敗したテスト：ベースブランチで合格し、ヘッドブランチで失敗したテストケース。
- 新たに発生したエラー：ベースブランチでは合格し、ヘッドブランチではテストエラーのために失敗したテストケース。
- 既存の失敗：ベースブランチで失敗し、ヘッドブランチでも失敗したテストケース。
- 解決済みの失敗：ベースブランチで失敗し、ヘッドブランチで合格したテストケース。
失敗したテストを見る
Test summary（テスト サマリー）パネルの各エントリには、テスト名と結果タイプが表示されます。テスト名を選択すると、実行時間とエラー出力の詳細が表示されたモーダルウィンドウが開きます。
失敗したテスト名のコピー
GitLab 15.2 で導入されました。
テストサマリーパネルに失敗したテストが表示されている場合、失敗したテストの名前とパスをコピーすることができます。名前とパスを使用して、検証のためにローカルでテストを検索し、再実行します。
すべての失敗したテストの名前をコピーするには、テスト サマリーパネルの上部で、失敗したテストのコピー を選択します。失敗したテストは、スペースで区切られた文字列として一覧表示されます。
単一の失敗したテストの名前をコピーするには、以下の手順に従います：
- テスト サマリーの詳細を表示（{chevron-lg-down}）を選択して、テスト サマリーパネルを展開します。
- レビューするテストを選択します。
- テスト名をコピーしてローカルで再実行する（{copy-to-clipboard}）を選択します。
最近の失敗回数
プロジェクトのデフォルトブランチで過去14日間にテストが失敗した場合、そのテストに対してFailed {n} time(s) in {default_branch} in the last 14 days のようなメッセージが表示されます。
設定方法
マージリクエストでユニットテストレポートを有効にするには、.gitlab-ci.ymlにartifacts:reports:junit を追加し、生成されるテストレポートのパスを指定する必要があります。レポートは.xml ファイルでなければなりません。そうでない場合、GitLab はエラー 500 を返します。
以下のRubyの例では、test ステージのジョブが実行され、GitLabはジョブからユニットテストレポートを収集します。ジョブが実行されると、XML レポートがアーティファクトとして GitLab に保存され、マージリクエストウィジェットに結果が表示されます。
## Use https://github.com/sj26/rspec_junit_formatter to generate a JUnit report format XML file with rspec
ruby:
stage: test
script:
- bundle install
- bundle exec rspec --format progress --format RspecJunitFormatter --out rspec.xml
artifacts:
when: always
paths:
- rspec.xml
reports:
junit: rspec.xml
ユニットテストレポートの出力ファイルを閲覧できるようにするには、例のようにartifacts:paths キーワードも含めます。ジョブが失敗した場合 (たとえばテストがパスしなかった場合) でもレポートをアップロードするには、artifacts:when:always キーワードを使用します。
JUnit レポート形式 XML ファイルに、同じ名前とクラスを持つ複数のテストを含めることはできません。
GitLab 15.0 以前では、parallel:matrixジョブのテストレポートが一緒に集約されるため、一部のレポート情報が表示されないことがありました。GitLab 15.1 以降ではこのバグが修正され、すべてのレポート情報が表示されるようになりました。
GitLab でユニットテストレポートを見る
JUnit レポート形式の XML ファイルがパイプラインの一部として生成されアップロードされた場合、これらのレポートはパイプラインの詳細ページで見ることができます。このページのTestsタブには、XML ファイルからレポートされたテストスイートとケースのリストが表示されます。
すべての既知のテスト スイートを表示し、それぞれを選択して、スイートを構成するケースなどの詳細 を表示できます。
また、GitLab API経由でレポートを取得できます。
ユニットテストのレポート解析エラー
GitLab 13.10で導入されました。
JUnit レポート XML の解析でエラーが発生した場合、ジョブ名の横にインジケータが表示されます。アイコンにカーソルを合わせると、ツールチップにパーサーエラーが表示されます。グループ化されたジョブから複数の解析エラーが発生した場合、GitLabはそのグループから最初のエラーだけを表示します。
テストケースの解析限界については、ユニットテストレポートあたりの最大テストケースを参照してください。
GitLabはJUnitレポートの非常に大きなノードを解析しません。これをオプションにするイシューがオープンされています。
GitLabでJUnitのスクリーンショットを見る
スクリーンショットをアーティファクトとしてGitLabにアップロードすることができます。JUnitレポートフォーマットのXMLファイルにattachment タグが含まれている場合、GitLabは添付ファイルを解析します。スクリーンショットのアーティファクトをアップロードする場合：
-
attachmentタグには、アップロードしたスクリーンショットの$CI_PROJECT_DIRへの相対パスを含める必要があります。例えば<testcase time="1.00" name="Test"> <system-out>[[ATTACHMENT|/path/to/some/file]]</system-out> </testcase> -
テストが失敗した場合でもスクリーンショットをアップロードするように、スクリーンショットをアップロードするジョブを
artifacts:when: alwaysに設定する必要があります。
添付ファイルがアップロードされると、パイプライン・テスト・レポートにはスクリーンショットへのリンクが含まれます：
トラブルシューティング
テストレポートに何も表示されない
レポートを含むアーティファクトの有効期限が切れると、ユニット テスト レポートがマージ リクエストで表示されたときに空に見えることがあります。アーティファクトの有効期限が早すぎる場合は、レポート アーティファクトにexpire_in より長い値を設定してください。
また、新しいパイプラインを実行して新しいレポートを生成することもできます。