.NET テスト

互換性

対応する .NET バージョン:

.NET Framework 4.6.1 以上
.NET Core 2.1、3.1、.NET 5、および .NET 6

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

xUnit 2.2 以上
NUnit 3.0 以上
MsTestV2 14 以上
BenchmarkDotNet 0.13.2 以上

テストスイートレベルの可視化の互換性

テストスイートレベルの可視化は dd-trace-dotnet>=2.16.0 からサポートされるようになりました。

報告方法の構成

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

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 .NET ライブラリのバージョン >= 2.5.1 で使用できます

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

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

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

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

.NET トレーサー CLI のインストール

以下のいずれかの方法で dd-trace コマンドをインストールまたは更新してください。

以下のコマンドを実行して、.NET SDK を使用する。
```
dotnet tool update -g dd-trace
```
適切なバージョンをダウンロードする。
- Win-x64: https://dtdg.co/dd-trace-dotnet-win-x64
- Linux-x64: https://dtdg.co/dd-trace-dotnet-linux-x64
- Linux-musl-x64 (Alpine): https://dtdg.co/dd-trace-dotnet-linux-musl-x64
または、github のリリースページよりダウンロードする。

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

注: BenchmarkDotNet の場合は、こちらの手順に従ってください。

テストスイートをインスツルメントするには、テストコマンドの前に dd-trace ci run を付け、テスト中のサービスまたはライブラリの名前を --dd-service パラメーターとして指定し、テストが実行されている環境 (たとえば、開発者ワークステーションでテストを実行する場合は local、CI プロバイダーでテストを実行する場合は ci) を --dd-env パラメーターとして使用します。例:

dotnet test の使用によって

dd-trace ci run --dd-service=my-dotnet-app --dd-env=ci -- dotnet test

VSTest.Console.exe の使用によって

dd-trace ci run --dd-service=my-dotnet-app --dd-env=ci -- VSTest.Console.exe {test_assembly}.dll

すべてのテストは自動的にインスツルメントされます。

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

コマンドライン引数または環境変数を使用して、CLI のデフォルトコンフィギュレーションを変更できます。コンフィギュレーション設定の完全なリストについては、以下を実行してください。

dd-trace ci run --help

次のリストは、主要なコンフィギュレーション設定のデフォルト値を示しています。

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

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

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

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

// テスト内
var scope = Tracer.Instance.ActiveScope; // from Datadog.Trace;
if (scope != null) {
    scope.Span.SetTag("test_owner", "my_team");
}
// テストは正常に続きます
// ...

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

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

ベンチマークテストをインスツルメンテーションするために必要なこと

Datadog.Trace.BenchmarkDotNet NuGet パッケージをプロジェクトに追加します (例えば、dotnet add package Datadog.Trace.BenchmarkDotNet を使用します)。
DatadogDiagnoser 属性または WithDatadog() 拡張機能を使って、 Datadog.Trace.BenchmarkDotNet エクスポーターを使用するようにプロジェクトを構成してください。例:

using BenchmarkDotNet.Attributes;
using Datadog.Trace.BenchmarkDotNet;

[DatadogDiagnoser]
[MemoryDiagnoser]
public class OperationBenchmark
{
    [Benchmark]
    public void Operation()
    {
        // ...
    }
}

using BenchmarkDotNet.Configs;
using BenchmarkDotNet.Running;
using Datadog.Trace.BenchmarkDotNet;

var config = DefaultConfig.Instance
              .WithDatadog();

BenchmarkRunner.Run<OperationBenchmark>(config);

報告方法を構成します。
通常通りベンチマークプロジェクトを実行すると、すべてのベンチマークテストが自動的にインスツルメンテーションされます。

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

Datadog は、テスト結果を可視化し、リポジトリ、ブランチ、コミットごとにグループ化するために Git の情報を使用します。Git のメタデータは、CI プロバイダーの環境変数や、プロジェクトパス内のローカルな .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

カスタムインスツルメンテーション

注: カスタムインスツルメンテーションの設定は、dd-trace のバージョンに依存します。カスタムインスツルメンテーションを使用するには、dd-trace と Datadog.Trace の NuGet パッケージのバージョンを同期させておく必要があります。

.NET アプリケーションでカスタムインスツルメンテーションを使用するには

ツールのバージョンを取得するには、dd-trace --version を実行します。
同じバージョンの Datadog.Trace NuGet パッケージをアプリケーションに追加します。
アプリケーションコードで、Datadog.Trace.Tracer.Instance プロパティを介してグローバルトレーサーにアクセスし、新しいスパンを作成します。

カスタムインスツルメンテーションのスパンやタグの追加方法については、.NET カスタムインスツルメンテーションのドキュメントを参照してください。