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

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 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 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" -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

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

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

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

$(./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

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

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 属性。

例:

<?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

<?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

<?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

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

その他の参考資料

お役に立つドキュメント、リンクや記事:

テスト結果とパフォーマンスを確認するドキュメント トラブルシューティング CIドキュメント