単体テストレポート

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

単体テストレポートは、マージリクエストとパイプラインの詳細でテスト結果を直接表示するため、ジョブログを検索しなくても失敗を特定できます。

次のような場合は、単体テストレポートを使用します。

マージリクエストでテストの失敗をすぐに確認する。
ブランチ間でテスト結果を比較する。
エラーの詳細とスクリーンショットを使用して、失敗したテストをデバッグする。
経時的なテスト失敗パターンを追跡する。

単体テストレポートにはJUnit XML形式が必要です。ただし、このレポートはジョブステータスには影響しません。テストが失敗したときにジョブを失敗させるには、ジョブのスクリプトを0以外のステータスで終了させる必要があります。

GitLab Runnerは、JUnit XML形式のテスト結果をアーティファクトとしてアップロードします。マージリクエストに移動すると、テスト結果はソースブランチ（head）とターゲットブランチ（base）の間で比較され、変更点が表示されます。

ファイル形式とサイズ制限

単体テストレポートでは、適切な解析と表示を確実に行うために、特定の要件を満たすJUnit XML形式を使用する必要があります。

ファイル要件

テストレポートファイルは、次の条件を満たす必要があります。

JUnit XML形式を使用し、ファイル拡張子は.xmlにする。
各ファイルのサイズは30 MB未満とする。
1つのジョブ内のすべてのJUnitファイルの合計サイズは100 MB未満とする。

テスト名が重複している場合は、最初のテストのみが使用され、同じ名前の他のテストは無視されます。

テストケースの制限については、単体テストレポートごとの最大テストケースを参照してください。

JUnit XML形式の仕様

GitLabは、JUnit XMLの要素と属性のサブセットを解析し、UIにテスト結果を表示します。

XML要素	XML属性	説明
`testsuites`	`time`	すべてのテストスイートの合計実行時間。テスト実行時間の計算に使用されます。
`testsuite`	`name`	テストスイート名。内部グループ化のために解析されます。
`testsuite`	`time`	個々のテストスイートの実行時間。テスト実行時間の計算に使用されます。
`testcase`	`classname`	テストクラス名またはカテゴリ名。UIにスイート名として表示されます。
`testcase`	`name`	個々のテスト名。
`testcase`	`file`	テストが定義されているファイルパス。
`testcase`	`time`	テスト実行時間（秒）。
`failure`	要素の内容	失敗メッセージとスタックトレース。
`error`	要素の内容	エラーメッセージとスタックトレース。
`skipped`	要素の内容	テストをスキップする理由。
`system-out`	要素の内容	システム出力とアタッチメントタグ。`testcase`要素からのみ解析されます。
`system-err`	要素の内容	システムエラー出力。`testcase`要素からのみ解析されます。

次の要素と属性は解析されません:

testsuite属性（テスト、失敗、エラー、タイムスタンプ）
testcase属性（アサーション、行、ステータス）
properties要素
testsuiteレベルでのsystem-outおよびsystem-err

XML構造の例

<testsuites>
  <testsuite name="Authentication Tests" tests="1" failures="1">
    <testcase classname="LoginTest" name="test_invalid_password" file="spec/auth_spec.rb" time="0.23">
      <failure>Expected authentication to fail</failure>
      <system-out>[[ATTACHMENT|screenshots/failure.png]]</system-out>
    </testcase>
  </testsuite>
</testsuites>

このXMLはGitLabでは次のように表示されます。

スイート: LoginTest（testcase classnameより）
名前: test_invalid_password（testcase nameより）
ファイル: spec/auth_spec.rb（testcase fileより）
時間: 0.23s（testcase timeより）
スクリーンショット: テストの詳細ダイアログで利用可能（testcase system-outより）
非表示: 「Authentication Tests」（testsuite nameより）

テスト結果タイプ

テスト結果は、マージリクエストのソースブランチとターゲットブランチの間で比較され、変更点が表示されます。

新たに失敗したテスト: ターゲットブランチでは成功したが、自分のブランチでは失敗したテスト。
新たに発生したエラー: ターゲットブランチでは成功したが、自分のブランチではエラーが発生したテスト。
既存の失敗: 両方のブランチで失敗したテスト。
解決済みの失敗: ターゲットブランチでは失敗したが、自分のブランチでは成功したテスト。

ブランチを比較できない場合（たとえば、ターゲットブランチのデータがまだない場合）は、自分のブランチで失敗したテストのみが表示されます。

過去14日間にデフォルトブランチで失敗したテストについては、次のようなメッセージが表示されます: Failed {n} time(s) in {default_branch} in the last 14 days。このカウントには、完了したパイプラインで失敗したテストが含まれますが、ブロックされたパイプラインで失敗したテストは含まれません。ブロックされたパイプラインのサポートは、イシュー431265で提案されています。

単体テストレポートを設定する

単体テストレポートを設定すると、マージリクエストとパイプラインにテスト結果を表示できます。

単体テストレポートを設定するには、次の手順に従います。

JUnit XML形式のテストレポートを出力するようにテストジョブを設定します。設定の詳細については、テストフレームワークのドキュメントを確認してください。
.gitlab-ci.ymlファイルで、テストジョブにartifacts:reports:junitを追加します。
XMLテストレポートファイルのパスを指定します。junitプロパティは以下を受け入れます:
- 単一のファイル名: junit: report.xml
- ファイル名パターン: junit: test-results/**/*.xml
- ファイル名の配列: junit: [rspec-1.xml, rspec-2.xml, rspec-3.xml]
- 両方の組み合わせ: junit: [rspec.xml, test-results/TEST-*.xml]
ディレクトリはサポートされていません（例: junit: test-resultsまたはjunit: test-results/**）。
オプション。レポートファイルを参照できるようにするには、artifacts:pathsにそれらのファイルを指定します。
オプション。ジョブが失敗した場合でもレポートをアップロードするには、artifacts:when:alwaysを使用します。

Rubyと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

次の場所でテスト結果を確認できます。

テストジョブの完了後、パイプラインの詳細のテストタブ。
パイプラインの完了後、マージリクエストのテストのサマリーパネル。

マージリクエストでテスト結果を表示する

マージリクエストでテスト失敗に関する詳細情報を表示します。

テストのサマリーパネルには、失敗したテストと成功したテストの数など、テスト結果の概要が表示されます。

テスト失敗の詳細を表示するには、次の手順に従います。

マージリクエストで、テストのサマリーパネルに移動します。
テストのサマリーパネルを展開するには、詳細を表示（）を選択します。
失敗したテストの横にある詳細を表示を選択します。

ダイアログには、テスト名、ファイルパス、実行時間、添付されたスクリーンショット（設定されている場合）、エラー出力が表示されます。

すべてのテスト結果を表示するには、次の手順に従います。

テストのサマリーパネルから、完全なレポートを選択して、パイプライン詳細のテストタブに移動します。

失敗したテスト名をコピーする

テスト名をコピーして、ローカルで再実行しデバッグします。

前提条件:

JUnitレポートに、失敗したテストの<file>属性が含まれている必要があります。

すべての失敗したテスト名をコピーするには、次の手順に従います。

テストのサマリーパネルから、失敗したテストをコピー（）を選択します。

失敗したテストは、スペースで区切られた文字列としてコピーされます。

失敗したテスト名を1つコピーするには、次の手順に従います。

テストのサマリーパネルを展開するには、詳細を表示（）を選択します。
コピーするテストの横にある詳細を表示を選択します。
ダイアログで、ローカルで再実行するためにテスト名をコピー（）を選択します。

テスト名がクリップボードにコピーされます。

パイプラインでテスト結果を表示する

パイプラインの詳細で、子パイプラインからの結果を含む、すべてのテストスイートとケースを表示します。

パイプラインのテスト結果を表示するには、次の手順に従います。

パイプラインの詳細ページに移動します。
テストタブを選択します。
任意のテストスイートを選択すると、個々のテストケースを確認できます。

パイプラインAPIを使用してテストレポートを取得することもできます。

テストタイミングメトリクス

テスト結果には、次のようなさまざまなタイミングメトリクスが表示されます。

パイプラインの所要時間: パイプラインが開始してから完了するまでの経過時間。

テスト実行時間: すべてのジョブにおけるすべてのテストの合計実行時間。

キュー時間: ジョブが利用可能なRunnerを待機していた時間。

ジョブが並列実行される場合、累積テスト実行時間がパイプラインの所要時間を超えることがあります。

パイプラインの所要時間は結果が得られるまでの時間を示し、テスト実行時間は使用されたコンピューティングリソースを示します。

たとえば、多数のテストジョブが複数のRunnerで並列実行された場合、81分で完了するパイプラインでも、テスト実行時間が9時間10分と表示されることがあります。

テストレポートにスクリーンショットを追加する

テスト失敗のデバッグを支援するために、テストレポートにスクリーンショットを追加します。

テストレポートにスクリーンショットを追加するには、次の手順に従います。

JUnit XMLファイルで、$CI_PROJECT_DIRを基準としたスクリーンショットの相対パスを指定し、添付ファイルタグを追加します。
```
<testcase time="1.00" name="Test">
  <system-out>[[ATTACHMENT|/path/to/some/file]]</system-out>
</testcase>
```

.gitlab-ci.ymlファイルで、スクリーンショットをアーティファクトとしてアップロードするようにジョブを設定します。

スクリーンショットファイルのパスを指定します。
オプション。テストが失敗した場合にスクリーンショットをアップロードするには、artifacts:when: alwaysを使用します。

例:

ruby:
  stage: test
  script:
    - bundle install
    - bundle exec rspec --format progress --format RspecJunitFormatter --out rspec.xml
    - # Your test framework should save screenshots to a directory
  artifacts:
    when: always
    paths:
      - rspec.xml
      - screenshots/
    reports:
      junit: rspec.xml

パイプラインを実行します。

テストのサマリーパネルで失敗したテストの詳細を表示を選択すると、テストの詳細ダイアログでスクリーンショットリンクにアクセスできます。

トラブルシューティング

テストレポートが空で表示される

マージリクエストで、テストのサマリーパネルが空の状態で表示される場合があります。

この問題は、次の場合に発生します:

レポートアーティファクトが期限切れになっている。
JUnitファイルがサイズ制限を超えている。

この問題を解決するには、レポートアーティファクトのexpire_in値をより長く設定するか、新しいパイプラインを実行して新しいレポートを生成します。

JUnitファイルがサイズ制限を超えている場合、次の内容を確認します。

個々のJUnitファイルが30 MB未満である。
ジョブのすべてのJUnitファイルの合計サイズが100 MB未満である。

カスタム制限のサポートは、エピック16374で提案されています。

テスト結果が欠落している

レポートで、予想よりも少ないテスト結果が表示される場合があります。

これは、JUnit XMLファイルに重複するテスト名がある場合に発生する可能性があります。それぞれの名前では最初のテストのみが使用され、重複は無視されます。

この問題を解決するには、すべてのテスト名とクラスが一意であることを確認してください。

マージリクエストにテストレポートが表示されない

マージリクエストでテストのサマリーパネルがまったく表示されない場合があります。

この問題は、ターゲットブランチに比較対象のテストデータがない場合に発生する可能性があります。

この問題を解決するには、ターゲットブランチでパイプラインを実行して、ベースラインテストデータを生成します。

JUnit XMLの解析エラー

パイプライン内のジョブ名の横に解析エラーインジケーターが表示される場合があります。

これは、JUnit XMLファイルに形式エラーまたは無効な要素が含まれている場合に発生する可能性があります。

この問題を解決するには:

JUnit XMLファイルが標準形式に従っていることを確認する。
すべてのXML要素が適切に閉じられていることを確認する。
属性名と値が正しい形式で記述されていることを確認する。

グループ化されたジョブでは、そのグループの最初の解析エラーのみが表示されます。