Java テスト

選択したサイト () では、現時点では CI Visibility は使用できません。

互換性

対応するテストフレームワーク:

  • JUnit >= 4.10 および >= 5.3
  • また、Spock Framework や Cucumber-Junit など、JUnit をベースにしたテストフレームワークも含まれます。: JUnit 4 を使用する Cucumber v1 のみがサポートされています。
  • TestNG >= 6.4

報告方法の構成

Datadog にテスト結果を報告するには、Datadog の Java ライブラリを構成する必要があります。

Jenkins や自己管理型の GitLab CI などのオンプレミス CI プロバイダーでテストを実行する場合、Agent インストール手順に従って各ワーカノードに Datadog Agent をインストールします。これは、テスト結果が自動的に基礎となるホストメトリクスにリンクされるため、推奨されるオプションです。

CI プロバイダーがコンテナベースのエグゼキューターを使用している場合、ビルド内の localhost の使用ではコンテナ自体を参照しており、Datadog Agent が動作している基礎となるワーカーノードではないため、すべてのビルドで DD_AGENT_HOST 環境変数 (デフォルトは http://localhost:8126) を、ビルドコンテナの中からアクセスできるエンドポイントに設定します。

Kubernetes のエグゼキューターを使用している場合、Datadog は Datadog Admission Controller の使用を推奨しており、これは自動的にビルドポッドの環境変数 DD_AGENT_HOST を設定してローカルの Datadog Agent と通信させます。

Agentless モードは、Datadog Java ライブラリのバージョン >= 0.101.0 で使用できます

GitHub Actions や CircleCI など、基盤となるワーカーノードにアクセスできないクラウド CI プロバイダーを使用している場合は、Agentless モードを使用するようにライブラリを構成します。そのためには、以下の環境変数を設定します。

DD_CIVISIBILITY_AGENTLESS_ENABLED=true (必須)
Agentless モードを有効または無効にします。
デフォルト: false
DD_API_KEY (必須)
テスト結果のアップロードに使用される Datadog API キー
デフォルト: (empty)

さらに、どの Datadog サイトにデータを送信するかを構成します。

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

Java トレーサーのインストール

Java トレーサー v0.101.0 以降をインストールし、有効にします。

ルートの pom.xml に新しい Maven プロファイルを追加し、Datadog Java トレーサーの依存関係と javaagent arg のプロパティを構成します。その際に、$VERSIONMaven リポジトリからアクセス可能なトレーサーの最新のバージョンで置き換えます (先行する v なし): Maven Central

pom.xml

<profile>
  <id>dd-civisibility</id>
  <activation>
    <activeByDefault>false</activeByDefault>
  </activation>
  <properties>
    <dd.java.agent.arg>-javaagent:${settings.localRepository}/com/datadoghq/dd-java-agent/$VERSION/dd-java-agent-$VERSION.jar -Ddd.service=my-java-app -Ddd.civisibility.enabled=true</dd.java.agent.arg>
  </properties>
  <dependencies>
    <dependency>
        <groupId>com.datadoghq</groupId>
        <artifactId>dd-java-agent</artifactId>
        <version>$VERSION</version>
        <scope>provided</scope>
    </dependency>
  </dependencies>
</profile>

ddTracerAgent エントリを configurations タスクブロックに追加し、Datadog Java トレーサーの依存関係を追加します。その際に、$VERSIONMaven リポジトリで利用可能なトレーサーの最新のバージョンで置き換えます (先行する v なし): Maven Central

build.gradle

configurations {
    ddTracerAgent
}
dependencies {
    ddTracerAgent "com.datadoghq:dd-java-agent:$VERSION"
}

Java コンパイラープラグインのインストール

Java コンパイラープラグインはトレーサーと連携し、ソースコードの情報を追加で提供します。 プラグインをインストールすることで、特定の CI visibility 機能のパフォーマンスと精度を向上させることができます。

このプラグインは標準的な javac コンパイラーで動作します (Eclipse JDT コンパイラーはサポートされていません)。

構成が成功すると、コンパイラーの出力に DatadogCompilerPlugin initialized という行が表示されるはずです。

トレーサー設定用のルート pom.xml に追加したのと同じ Maven プロファイルの関連セクションに、以下のスニペットを含めます。 $VERSION は、Maven リポジトリからアクセスできるアーティファクトの最新バージョンに置き換えてください (前の v は削除してください): Maven Central

pom.xml

<dependency>
    <groupId>com.datadoghq</groupId>
    <artifactId>dd-javac-plugin-client</artifactId>
    <version>$VERSION</version>
</dependency>

pom.xml

<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-compiler-plugin</artifactId>
            <version>3.5</version>
            <configuration>
                <annotationProcessorPaths>
                    <annotationProcessorPath>
                        <groupId>com.datadoghq</groupId>
                        <artifactId>dd-javac-plugin</artifactId>
                        <version>$VERSION</version>
                    </annotationProcessorPath>
                </annotationProcessorPaths>
                <compilerArgs>
                    <arg>-Xplugin:DatadogCompilerPlugin</arg>
                </compilerArgs>
            </configuration>
        </plugin>
    </plugins>
</build>

Maven コンパイラープラグインは、バージョン 3.5 から annotationProcessorPaths プロパティをサポートしています。どうしても古いバージョンを使用したい場合は、プロジェクトで Datadog コンパイラープラグインを通常の依存関係として宣言してください。

さらに、JDK 16 以降を使用している場合は、プロジェクトのベースディレクトリにある .mvn/jvm.config ファイルに以下の行を追加してください。

.mvn/jvm.config

--add-exports=jdk.compiler/com.sun.tools.javac.api=ALL-UNNAMED
--add-exports=jdk.compiler/com.sun.tools.javac.code=ALL-UNNAMED
--add-exports=jdk.compiler/com.sun.tools.javac.tree=ALL-UNNAMED
--add-exports=jdk.compiler/com.sun.tools.javac.util=ALL-UNNAMED

plugin-client JAR をプロジェクトのクラスパスに追加し、plugin JAR をコンパイラーのアノテーション処理系パスに追加し、Java クラスをコンパイルするタスクに plugin の引数を渡します。

$VERSION は、Maven リポジトリからアクセスできるアーティファクトの最新バージョンに置き換えてください (前の v は削除してください): Maven Central

build.gradle

if (project.hasProperty("dd-civisibility")) {
    dependencies {
        implementation 'com.datadoghq:dd-javac-plugin-client:$VERSION'
        annotationProcessor 'com.datadoghq:dd-javac-plugin:$VERSION'
        testAnnotationProcessor 'com.datadoghq:dd-javac-plugin:$VERSION'
    }

    tasks.withType(JavaCompile).configureEach {
        options.compilerArgs.add('-Xplugin:DatadogCompilerPlugin')
    }
}

さらに、JDK 16 以降を使用している場合は、gradle.properties ファイルに以下の行を追加してください。

gradle.properties

org.gradle.jvmargs=\
--add-exports=jdk.compiler/com.sun.tools.javac.api=ALL-UNNAMED  \
--add-exports=jdk.compiler/com.sun.tools.javac.code=ALL-UNNAMED \
--add-exports=jdk.compiler/com.sun.tools.javac.tree=ALL-UNNAMED \
--add-exports=jdk.compiler/com.sun.tools.javac.util=ALL-UNNAMED

テストのインスツルメンテーション

Maven Surefire プラグインまたは Maven Failsafe プラグイン (または両方を使用する場合は両方) を構成して、Datadog Java Agent を使用し、テスト対象のサービスまたはライブラリの名前を -Ddd.service プロパティで指定します。

pom.xml

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-surefire-plugin</artifactId>
  <configuration>
    <argLine>${dd.java.agent.arg}</argLine>
  </configuration>
</plugin>

pom.xml

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-failsafe-plugin</artifactId>
  <configuration>
     <argLine>${dd.java.agent.arg}</argLine>
  </configuration>
  <executions>
      <execution>
        <goals>
           <goal>integration-test</goal>
           <goal>verify</goal>
        </goals>
      </execution>
  </executions>
</plugin>

DD_ENV 環境変数でテストを実行する環境 (たとえば、開発者ワークステーションでテストを実行する場合は local、CI プロバイダーでテストを実行する場合は ci) を指定して、通常どおりにテストを実行します。例:

DD_ENV=ci mvn clean verify -Pdd-civisibility

configurations.ddTracerAgent プロパティに基づいて Datadog Java トレーサーをターゲットとする -javaagent 引数を jvmArgs 属性に追加し、-Ddd.service プロパティでテスト対象のサービスまたはライブラリの名前を指定して、test Gradle タスクを構成します。

build.gradle

test {
  if(project.hasProperty("dd-civisibility")) {
    jvmArgs = ["-javaagent:${configurations.ddTracerAgent.asPath}", "-Ddd.service=my-java-app", "-Ddd.civisibility.enabled=true"]
  }
}

DD_ENV 環境変数でテストを実行する環境 (たとえば、開発者ワークステーションでテストを実行する場合は local、CI プロバイダーでテストを実行する場合は ci) を指定して、通常どおりにテストを実行します。例:

DD_ENV=ci ./gradlew cleanTest test -Pdd-civisibility --rerun-tasks

注: Gradle でのビルドはプログラムを通じてカスタマイズできるため、これらのステップを特定のビルドコンフィギュレーションに適応させなければならない場合があります。

テストにカスタムタグを追加する

現在アクティブなスパンを使用して、テストにカスタムタグを追加することができます。

// テスト内
final Span span = GlobalTracer.get().activeSpan();
if (span != null) {
  span.setTag("test_owner", "my_team");
}
// テストは正常に続きます
// ...

これらのタグに対して、フィルターや group by フィールドを作成するには、まずファセットを作成する必要があります。タグの追加についての詳細は、Java カスタムインスツルメンテーションドキュメントのタグの追加セクションを参照してください。

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

次のシステムプロパティはコンフィギュレーションのオプションを設定するもので、環境変数と同等の値を持ちます。両方に同じキータイプが設定されている場合は、システムプロパティコンフィギュレーションが優先されます。 システムプロパティは、JVM フラグとして設定できます。

dd.service
テスト中のサービスまたはライブラリの名前。
環境変数: DD_SERVICE
デフォルト: unnamed-java-app
: my-java-app
dd.env
テストが実行されている環境の名前。
環境変数: DD_ENV
デフォルト: none
: localci
dd.trace.agent.url
http://hostname:port の形式のトレース収集用の Datadog Agent URL。
環境変数: DD_TRACE_AGENT_URL
デフォルト: http://localhost:8126

他のすべての Datadog トレーサーコンフィギュレーションオプションも使用できます。

重要: インテグレーションテストを行う際に、より多くのインテグレーションを有効化したい場合があるかもしれません。特殊なインテグレーションを有効化するには、Datadog Tracer Compatibility テーブルを使用してインテグレーションテスト用のカスタム設定を作成してください。

たとえば、OkHttp3 クライアントリクエストのインテグレーションを有効化する場合は、設定に -Ddd.integration.okhttp-3.enabled=true を追加します。

Git のメタデータを収集する

Datadog は、テスト結果を可視化し、リポジトリ、ブランチ、コミットごとにグループ化するために Git の情報を使用します。Git のメタデータは、CI プロバイダーの環境変数や、プロジェクトパス内のローカルな .git フォルダがあれば、そこからテストインスツルメンテーションによって自動的に収集されます。

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

DD_GIT_REPOSITORY_URL
コードが格納されているリポジトリの URL。HTTP と SSH の両方の URL に対応しています。
: git@github.com:MyCompany/MyApp.githttps://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

収集した情報

CI Visibility を有効にすると、プロジェクトから以下のデータが収集されます。

  • テストの名前と時間。
  • CI プロバイダーが設定する事前定義された環境変数。
  • Git のコミット履歴。ハッシュ、メッセージ、作成者情報、変更されたファイル (ファイルの内容は含まず) が含まれます。
  • CODEOWNERS ファイルからの情報。

トラブルシューティング

トレーサーで CI Visibility を有効にした後、Datadog にテストが表示されない

Datadog にテストが表示されない場合は、Java トレーサのバージョン 0.91.0 以降を使用していることを確認してください。 -Ddd.civisibility.enabled=true のコンフィギュレーションプロパティは、そのバージョン以降でのみ利用可能です。

以前のバージョンのトレーサーを使用する必要がある場合、以下のシステムプロパティを使用して CI Visibility を構成することができます。

-Ddd.prioritization.type=ENSURE_TRACE -Ddd.jmxfetch.enabled=false -Ddd.integrations.enabled=false -Ddd.integration.junit.enabled=true -Ddd.integration.testng.enabled=true

その他の参考資料