JUnit テストレポートファイルを Datadog にアップロードする

Docs > Continuous Integration Visibility > テストの確認 > JUnit テストレポートファイルを Datadog にアップロードする

注: Datadog では、JUnit XML ファイルのアップロードよりもネイティブインスツルメンテーションを推奨しています。ネイティブインスツルメンテーションは、より正確な時間結果を提供し、インテグレーションテストでの分散型トレーシングをサポートし、構造化スタックトレースをサポートするからです。

JUnit テストレポートファイルは、テスト名とスイート名、合格/不合格ステータス、期間、場合によってはエラーログなどのテスト実行情報を含む XML ファイルです。JUnit テストフレームワークによって導入されましたが、他の多くの一般的なフレームワークは、この形式を使用して結果を出力できます。

テストフレームワークで JUnit XML のテストレポートを生成できる場合、Datadog トレーサーを使用したネイティブのテストインスツルメンテーションに代わる軽量な方法として、これらを使用することができます。JUnit XML レポートからインポートされたテスト結果は、トレーサーからレポートされたテストデータと一緒に表示されます。

Datadog CI CLI のインストール

npm を使用して datadog-ci CLI をグローバルにインストールします。

npm install -g @datadog/datadog-ci

スタンドアロンバイナリ (ベータ版)

注: スタンドアロンバイナリはベータ版であり、その安定性は保証されていません。

CI で Node.js をインストールすることに問題がある場合は、スタンドアロンバイナリが Datadog CI リリースで提供されています。linux-x64、darwin-x64 (MacOS)、win-x64 (Windows) のみがサポートされています。インストールするには、ターミナルで以下を実行します。

curl -L --fail "https://github.com/DataDog/datadog-ci/releases/latest/download/datadog-ci_linux-x64" --output "/usr/local/bin/datadog-ci" && chmod +x /usr/local/bin/datadog-ci

次に、datadog-ci と任意のコマンドを実行します:

datadog-ci version

curl -L --fail "https://github.com/DataDog/datadog-ci/releases/latest/download/datadog-ci_darwin-x64" --output "/usr/local/bin/datadog-ci" && chmod +x /usr/local/bin/datadog-ci

次に、datadog-ci と任意のコマンドを実行します:

datadog-ci version

Invoke-WebRequest -Uri "https://github.com/DataDog/datadog-ci/releases/latest/download/datadog-ci_win-x64.exe" -OutFile "datadog-ci.exe"

次に、Start-Process -FilePath "datadog-ci.exe" と任意のコマンドを実行します:

Start-Process -FilePath "./datadog-ci.exe" -ArgumentList version

テストレポートのアップロード

JUnit XML テストレポートを Datadog にアップロードするには、次のコマンドを実行し、--service パラメーターを使用してテストされたサービスまたはライブラリの名前と、XML レポートファイルまたはそれらを含むディレクトリへの 1 つ以上のファイルパスを指定します。

datadog-ci junit upload --service <service_name> <path> [<path> ...]

DATADOG_API_KEY 環境変数に有効な Datadog API キーを指定し、DD_ENV 環境変数にテストが実行された環境を指定します (たとえば、開発者ワークステーションから結果をアップロードする場合は local、CI プロバイダーから結果をアップロードする場合は ci)。例:


DD_ENV=ci DATADOG_API_KEY=<api_key> DATADOG_SITE= datadog-ci junit upload \
  --service my-api-service \
  unit-tests/junit-reports e2e-tests/single-report.xml

テストが失敗した場合でも、CI でこのコマンドが実行されることを確認してください。通常、テストが失敗すると、CI のジョブは実行を中止し、アップロードコマンドは実行されません。

ステータスチェック関数を使用します。

steps:
  - name: Run tests
    run: ./run-tests.sh
  - name: Upload test results to Datadog
    if: always()
    run: datadog-ci junit upload --service service_name ./junit.xml

after_script セクションを使用します。

test:
  stage: test
  script:
    - ./run-tests.sh
  after_script:
    - datadog-ci junit upload --service service_name ./junit.xml

post セクションを使用します。

pipeline {
  agent any
  stages {
    stage('Run tests') {
      steps {
        sh './run-tests.sh'
      }
      post {
        always {
          sh 'datadog-ci junit upload --service service_name ./junit.xml'
        }
      }
    }
  }
}

CI システムがサブシェルを許可している場合

$(./run-tests.sh); export tests_exit_code=$?
datadog-ci junit upload --service service_name ./junit.xml
if [ $tests_exit_code -ne 0 ]; then exit $tests_exit_code; fi

注: 250 MiB より大きいレポートは欠落したテストかログに終って完全に処理されないかもしれません。最高の体験を得るために、レポートは 250 MiB 以下であることを確認してください。

コンフィギュレーション設定

これは、datadog-ci junit upload コマンドを使用するときに使用できるオプションの完全なリストです。

--service (必須): テスト中のサービスまたはライブラリの名前。
環境変数: DD_SERVICE
例: my-api-service
--env: テストが実行された環境。
環境変数: DD_ENV
例: ci
--tags: すべてのテストにアタッチされる key:value 形式のキーと値のペア (--tags パラメーターは複数回指定できます)。DD_TAGS を使用してタグを指定する場合は、カンマを使用してタグを区切ります (例: team:backend,priority:high)。
環境変数: DD_TAGS
デフォルト: (none)
例: team:backend
注: --tags と DD_TAGS 環境変数を使用して指定されたタグがマージされます。--tags と DD_TAGS の両方に同じキーが表示される場合、環境変数 DD_TAGS の値が優先されます。
--xpath-tag: キーと xpath 表現を key=expression の形式で指定します。これにより、ファイル内のテスト用タグをカスタマイズできます (--xpath-tag パラメーターは複数回指定できます)。
サポートされている表現の詳細については、XPath 表現によるメタデータの提供を参照してください。
デフォルト: (none)
例: test.suite=/testcase/@classname
注: --xpath-tag を使用し、--tags または DD_TAGS 環境変数とともに指定されたタグはマージされます。xpath-tag の値は通常テストごとに異なるため、最優先されます。
--logs (ベータ版): XML レポートの内容を Logs として転送できるようにします。<system-out>、<system-err>、<failure> 内のコンテンツはログとして収集されます。<testcase> 内の要素からのログは自動的にテストに接続されます。
環境変数: DD_CIVISIBILITY_LOGS_ENABLED
デフォルト: false
注: Logs は CI Visibility とは別請求となります。
--max-concurrency: API への同時アップロードの数。
デフォルト: 20
--dry-run: 実際にファイルを Datadog にアップロードせずにコマンドを実行します。他のすべてのチェックが実行されます。
デフォルト: false
位置引数: JUnit XML レポートが配置されているファイルパスまたはディレクトリ。ディレクトリを渡すと、CLI はその中のすべての .xml ファイルを検索します。

次の環境変数がサポートされています。

DATADOG_API_KEY (必須): リクエストの認証に使用される Datadog API キー。
デフォルト: (なし)

さらに、選択したサイトを使用するように Datadog サイトを構成します ():

DATADOG_SITE (必須): 結果をアップロードする Datadog サイト。
デフォルト: datadoghq.com
選択したサイト:

リポジトリの収集とメタデータのコミット

Datadog は、テスト結果を可視化し、リポジトリやコミットごとにグループ化するために Git 情報を使用します。Git のメタデータは、Datadog の CI CLI が CI プロバイダーの環境変数やプロジェクトパスのローカルな .git フォルダ (あれば) から収集します。このディレクトリを読み込むには、git バイナリが必要です。

サポートされていない CI プロバイダーでテストを実行する場合や、.git フォルダがない場合は、環境変数を使って Git の情報を手動で設定することができます。これらの環境変数は、自動検出された情報よりも優先されます。Git の情報を提供するために、以下の環境変数を設定します。

DD_GIT_REPOSITORY_URL: コードが格納されているリポジトリの URL。HTTP と SSH の両方の URL に対応しています。
例: git@github.com:MyCompany/MyApp.git、https://github.com/MyCompany/MyApp.git
DD_GIT_BRANCH: テスト中の Git ブランチ。タグ情報を指定する場合は、空のままにしておきます。
例: develop
DD_GIT_TAG: テストされる Git タグ (該当する場合)。ブランチ情報を指定する場合は、空のままにしておきます。
例: 1.0.1
DD_GIT_COMMIT_SHA: フルコミットハッシュ。
例: a18ebf361cc831f5535e58ec4fae04ffd98d8152
DD_GIT_COMMIT_MESSAGE: コミットのメッセージ。
例: Set release number
DD_GIT_COMMIT_AUTHOR_NAME: コミット作成者名。
例: John Smith
DD_GIT_COMMIT_AUTHOR_EMAIL: コミット作成者メールアドレス。
例: john@example.com
DD_GIT_COMMIT_AUTHOR_DATE: ISO 8601 形式のコミット作成者の日付。
例: 2021-03-12T16:00:28Z
DD_GIT_COMMIT_COMMITTER_NAME: コミットのコミッター名。
例: Jane Smith
DD_GIT_COMMIT_COMMITTER_EMAIL: コミットのコミッターのメールアドレス。
例: jane@example.com
DD_GIT_COMMIT_COMMITTER_DATE: ISO 8601 形式のコミットのコミッターの日付。
例: 2021-03-12T16:00:28Z

Git メタデータのアップロード

datadog-ci バージョン 2.9.0 以降では、CI Visibility は Git のメタデータ情報 (コミット履歴) を自動的にアップロードします。このメタデータには、ファイル名は含まれていますが、ファイルのコンテンツは含まれていません。この動作を無効にしたい場合は、フラグ --skip-git-metadata-upload を渡します。

環境構成メタデータの収集

Datadog では、特別な専用タグを使用して、OS、ランタイム、デバイス情報など、テストが実行される環境の構成を特定します (該当する場合)。同じコミットに対する同じテストが複数の構成で実行される場合 (例えば、Windows 上と Linux 上)、タグは障害やフレーク性の検出におけるテストの区別に使用されます。

これらの特別なタグは、 datadog-ci junit upload を呼び出すときに --tags パラメーターを使用するか、環境変数 DD_TAGS を設定することで指定することができます。

これらのタグはすべて任意であり、指定したものだけが環境構成の区別に使用されます。

test.bundle: テストスイートのグループを個別に実行するために使用します。
例: ApplicationUITests、ModelTests
os.platform: オペレーティングシステムの名称。
例: windows、linux、darwin
os.version: オペレーティングシステムのバージョン。
例: 10.15.4、14.3.2、95
os.architecture: オペレーティングシステムのアーキテクチャ。
例: x64、x86、arm64
runtime.name: 言語インタープリターまたはプログラミングランタイムの名前。
例: .NET、.NET Core、OpenJDK Runtime Environment、Java(TM) SE Runtime Environment、CPython
runtime.version: ランタイムのバージョン。
例: 5.0.0, 3.1.7
runtime.vendor: ランタイムベンダーの名前 (該当する場合)。例えば、Java ランタイムを使用する場合。
例: AdoptOpenJDK、Oracle Corporation
runtime.architecture: ランタイムのアーキテクチャ。
例: x64、x86、arm64

モバイルアプリの場合 (Swift、Android):

device.model: テストするデバイスのモデル。
例: iPhone11,4、AppleTV5,3
device.name: テストするデバイスの名前。
例: iPhone 12 Pro Simulator、iPhone 13 (QA team)

XPath 表現によるメタデータの提供

アップロードされた XML レポートに含まれるすべてのテストにカスタムタグをグローバルに適用する --tags CLI パラメーターと DD_TAGS 環境変数に加え、--xpath-tag パラメーターは、XML 内の各種属性から各テストにタグを追加するカスタムルールを提供します。

提供されるパラメーターは key=expression の形式でなければならず、key は追加されるカスタムタグの名前、expression はサポートされている有効な XPath 表現になります。

XPath 構文が馴染みが深いため使用されますが、サポートされている表現は下記のみとなります。

/testcase/@attribute-name: <testcase attribute-name="value"> の XML 属性。
/testcase/../@attribute-name: 現在の <testcase> の親 <testsuite attribute-name="value"> の XML 属性。
/testcase/..//property[@name='property-name']: 現在の <testcase> の親の <testsuite> 内の<property name="property-name" value="value"> の value 属性。
/testcase//property[@name='property-name']: 現在の <testcase> 内の <property name="property-name" value="value"> value 属性。

例:

テストの test.suite タグは、デフォルトで <testsuite name="suite name"> から読み込まれます。ただし、一部のプラグインでは、<testcase classname="TestSuite"> でより良い値が報告される可能性があります。

test.suite タグを value 1、value 2 から SomeTestSuiteClass、OtherTestSuiteClass に変更する方法:

<?xml version="1.0" encoding="UTF-8"?>
<testsuites>
  <testsuite tests="1" failures="0" time="0.030000" name="value 1">
    <testcase classname="SomeTestSuiteClass" name="test_something" time="0.030000"></testcase>
  </testsuite>
  <testsuite tests="1" failures="0" time="0.021300" name="value 2">
    <testcase classname="OtherTestSuiteClass" name="test_something" time="0.021300"></testcase>
  </testsuite>
</testsuites>

datadog-ci junit upload --service service_name \
  --xpath-tag test.suite=/testcase/@classname ./junit.xml

各テストに value 1、value 2の値とともに custom_tag を追加する方法:

<?xml version="1.0" encoding="UTF-8"?>
<testsuites>
  <testsuite tests="1" failures="0" time="0.020000" name="SomeTestSuiteClass">
    <testcase name="test_something" time="0.010000" attr="value 1"></testcase>
    <testcase name="test_other" time="0.010000" attr="value 2"></testcase>
  </testsuite>
</testsuites>

datadog-ci junit upload --service service_name \
  --xpath-tag custom_tag=/testcase/@attr ./junit.xml

各テストに value 1、value 2の値とともに custom_tag を追加する方法:

<?xml version="1.0" encoding="UTF-8"?>
<testsuites>
  <testsuite tests="1" failures="0" time="0.030000" name="SomeTestSuiteClass">
    <properties>
      <property name="prop" value="value 1"></property>
    </properties>
    <testcase name="test_something" time="0.030000" attr="value 1"></testcase>
  </testsuite>
  <testsuite tests="1" failures="0" time="0.021300" name="OtherTestSuiteClass">
    <properties>
      <property name="prop" value="value 1"></property>
    </properties>
    <testcase name="test_something" time="0.021300" attr="value 1"></testcase>
  </testsuite>
</testsuites>

datadog-ci junit upload --service service_name \
  --xpath-tag custom_tag=/testcase/..//property[@name=\'prop\'] ./junit.xml

注: 名前は引用符で囲む必要があります。Bash では、バックスラッシュを使って引用符をエスケープしなければなりません。例えば、[@name='prop'] は `[@name='prop'] と入力します。

`<property>` 要素によるメタデータの提供

特定のテストに追加のタグを指定するもう 1 つの方法は、<testsuite> または <testcase> 要素内に <property name="dd_tags[key]" value="value"> 要素を含める方法です。これらのタグを <testcase> 要素に追加すると、そのテストスパンにタグが格納されます。タグを <testsuite> 要素に追加すると、そのスイートの全てのテストスパンにタグが格納されます。

この処理を行うには、 <property> 要素の name 属性が dd_tags[key] という形式である必要があります。ここで key は追加されるカスタムタグの名前です。その他のプロパティは無視されます。

例: <testcase> 要素にタグを追加する。

<?xml version="1.0" encoding="UTF-8"?>
<testsuites>
  <testsuite tests="1" failures="0" time="0.030000" name="SomeTestSuiteClass">
    <testcase classname="SomeTestSuiteClass" name="test_something" time="0.010000">
      <properties>
        <property name="dd_tags[custom_tag]" value="some value"></property>
        <property name="dd_tags[runtime.name]" value="CPython"></property>
      </properties>
    </testcase>
  </testsuite>
</testsuites>

例: <testsuite> 要素にタグを追加する。

<?xml version="1.0" encoding="UTF-8"?>
<testsuites>
  <testsuite tests="1" failures="0" time="0.030000" name="SomeTestSuiteClass">
    <properties>
      <property name="dd_tags[custom_tag]" value="some value"></property>
      <property name="dd_tags[runtime.name]" value="CPython"></property>
    </properties>
    <testcase classname="SomeTestSuiteClass" name="test_something" time="0.010000"></testcase>
  </testsuite>
</testsuites>