互換性

対応言語:

対応プラットフォーム:

Swift テスト用 SDK のインストール

テストフレームワークのインストール方法は 3 つあります。

Xcode プロジェクトの使用

1. プロジェクトに dd-sdk-swift-testing パッケージを追加します。これは、https://github.com/DataDog/dd-sdk-swift-testing にあります。

2. パッケージに含まれるライブラリ DatadogSDKTesting とテストターゲットをリンクします。

3. UITests を実行する場合は、テストを実行するアプリもこのライブラリでリンクします。

Swift パッケージプロジェクトの使用

1. パッケージの依存関係の配列に dd-sdk-swift-testing を追加します。例:

Copy

.package(url: "https://github.com/DataDog/dd-sdk-swift-testing.git", from: "2.2.0")

2. テスト対象の依存関係にテストフレームワークを追加するには、以下の行をテスト対象の依存関係の配列に追加します。

Copy

.product(name: "DatadogSDKTesting", package: "dd-sdk-swift-testing")

3. UITests を実行する場合は、テストを実行するアプリケーションにも依存関係を追加します。

1. DatadogSDKTesting 依存関係を Podfile のテストターゲットに追加します。

Copy

target 'MyApp' do
  # ...

  target 'MyAppTests' do
    inherit! :search_paths
    pod 'DatadogSDKTesting'
  end
end

2. UITests を実行する場合は、テストを実行するアプリにも依存関係を追加します。

1. リリースのページから DatadogSDKTesting.zip をダウンロードし、解凍します。

2. 出来上がった XCFramework にテストターゲットをコピーしてリンクします。

3. UITests を実行する場合は、テストを実行するアプリもこのライブラリでリンクします。

GitHub を使用している場合、GitHub Marketplace から Swift テストアクションを使用して、テストを自動的に構成して実行することができます。デフォルトでは、このページで説明されている残りの構成はスキップできますが (アクション自体の構成を除く)、設定環境変数を使って、追加機能の無効化や設定をすることができます。

Cocoapods やフレームワークのリンクなど他の方法と比較して、Swift テストアクションオプションは設定や実行の柔軟性に欠ける可能性がありますが、コードの変更は必要ありません。

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

Datadog の構成

Xcode プロジェクトの使用

テストのインスツルメンテーションを有効にするには、テストターゲットに以下の環境変数を追加するか、または以下で説明されているとおり Info.plist ファイルに追加します。テストプランを使用している場合は、Expand variables based on または Target for Variable Expansion でメインターゲットを選択する必要があります。

UITests の場合、フレームワークがこれらの値をアプリケーションに自動で注入するため、環境変数はテストターゲットにのみ設定する必要があります。

Swift パッケージプロジェクトの使用

テストのインスツルメンテーションを有効にするには、以下の環境変数をテストのコマンドライン実行に設定する必要があります。代わりに、テストを実行する前に環境に設定することもできますし、コマンドに前置きすることもできます。

DD_TEST_RUNNER=1 DD_API_KEY= DD_APPLICATION_KEY= DD_SITE=us1 SRCROOT=$PWD swift test ...

or

DD_TEST_RUNNER=1 DD_API_KEY= DD_APPLICATION_KEY= DD_SITE=us1 SRCROOT=$PWD xcodebuild test -scheme ...

テストターゲットにこれらすべての変数を設定します。

DD_TEST_RUNNER

テストのインスツルメンテーションを有効または無効にします。この値を $(DD_TEST_RUNNER) に設定すると、テストプロセスの外部 (CI ビルドなど) で定義された環境変数を使用してテストインスツルメンテーションを有効または無効にできます。
デフォルト: false
推奨: $(DD_TEST_RUNNER)

DD_API_KEY

テスト結果のアップロードに使用される Datadog API キー。
デフォルト: (empty)

DD_APPLICATION_KEY

テスト結果のアップロードに使用される Datadog アプリケーションキー。
デフォルト: (empty)

DD_SERVICE

テスト対象のサービスまたはライブラリの名前。
デフォルト: リポジトリ名
例: my-ios-app

DD_ENV

テストが実行されている環境の名前。この値を $(DD_ENV) に設定して、実行時に環境変数を使用して設定できるようにします。
デフォルト: none
推奨: $(DD_ENV)
例: ci、local

SRCROOT

プロジェクトの場所へのパス。Xcode を使用している場合、この値は自動的に設定されるため、$(SRCROOT) を使用します。
デフォルト: (empty)
推奨: $(SRCROOT)
例: /Users/ci/source/MyApp

service と env の予約タグの詳細については、統合サービスタグ付けを参照してください。

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

DD_SITE (必須)

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

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

Datadog uses Git information for visualizing your test results and grouping them by repository, branch, and commit. Git metadata is automatically collected by the test instrumentation from CI provider environment variables and the local .git folder in the project path, if available.

If you are running tests in non-supported CI providers or with no .git folder, you can set the Git information manually using environment variables. These environment variables take precedence over any auto-detected information. Set the following environment variables to provide Git information:

DD_GIT_REPOSITORY_URL

URL of the repository where the code is stored. Both HTTP and SSH URLs are supported.
Example: git@github.com:MyCompany/MyApp.git, https://github.com/MyCompany/MyApp.git

DD_GIT_BRANCH

Git branch being tested. Leave empty if providing tag information instead.
Example: develop

DD_GIT_TAG

Git tag being tested (if applicable). Leave empty if providing branch information instead.
Example: 1.0.1

DD_GIT_COMMIT_SHA

Full commit hash.
Example: a18ebf361cc831f5535e58ec4fae04ffd98d8152

DD_GIT_COMMIT_MESSAGE

Commit message.
Example: Set release number

DD_GIT_COMMIT_AUTHOR_NAME

Commit author name.
Example: John Smith

DD_GIT_COMMIT_AUTHOR_EMAIL

Commit author email.
Example: john@example.com

DD_GIT_COMMIT_AUTHOR_DATE

Commit author date in ISO 8601 format.
Example: 2021-03-12T16:00:28Z

DD_GIT_COMMIT_COMMITTER_NAME

Commit committer name.
Example: Jane Smith

DD_GIT_COMMIT_COMMITTER_EMAIL

Commit committer email.
Example: jane@example.com

DD_GIT_COMMIT_COMMITTER_DATE

Commit committer date in ISO 8601 format.
Example: 2021-03-12T16:00:28Z

テストの実行

インストール後、通常どおりにテストを実行します。たとえば、xcodebuild test コマンドを使用します。テスト、ネットワークリクエスト、アプリケーションクラッシュは自動的に記録されます。CI でテストを実行するときに、環境変数を渡します。次に例を示します。

DD_TEST_RUNNER=1 DD_ENV=ci DD_SITE= xcodebuild \
  -project "MyProject.xcodeproj" \
  -scheme "MyScheme" \
  -destination "platform=macOS,arch=x86_64" \
  test

UI テスト

UITests では、テストターゲットと UITests から実行されるアプリケーションの両方がフレームワークとリンクしている必要があります。フレームワークがこれらの値をアプリケーションに自動で注入するため、環境変数はテストターゲットにのみ設定する必要があります。

RUM インテグレーション

テスト対象のアプリケーションが RUM を使用してインスツルメンテーションされている場合、UI テストの結果と生成された RUM セッションは自動的にリンクされます。RUM の詳細については、RUM iOS インテグレーションガイドを参照してください。iOS RUM バージョン 1.10 以上が必要です。

追加のオプション構成

以下の構成設定の場合:

• Boolean 変数には 1、0、true、false、YES、NO のいずれかを使用できます
• String リスト変数には , または ; で区切られた要素の一覧が許可されます

自動インスツルメンテーションの有効化

DD_ENABLE_STDOUT_INSTRUMENTATION

stdout に書き込まれたメッセージ (例えば print()) をキャプチャして、ログとして報告します。これは請求額に影響を与える可能性があります。(ブール値)

DD_ENABLE_STDERR_INSTRUMENTATION

stderr に書き込まれたメッセージ (例えば NSLog() や UITest のステップ) をキャプチャして、ログとして報告します。これは請求額に影響を与える可能性があります。(ブール値)

自動インスツルメンテーションの無効化

このフレームワークでは、サポートされているすべてのライブラリの自動インスツルメンテーションが可能ですが、これが望ましくない場合もあります。次の環境変数を（または以下で説明されているとおり Info.plist ファイルに）設定することにより、特定のライブラリの自動インスツルメンテーションを無効にできます。

DD_DISABLE_NETWORK_INSTRUMENTATION

すべてのネットワークインスツルメンテーションを無効化します (Boolean)

DD_DISABLE_RUM_INTEGRATION

RUMセッションとのインテグレーションを無効にします (Boolean)

DD_DISABLE_SOURCE_LOCATION

テストのソースコードの場所と Codeowners を無効にします (ブール値)

DD_DISABLE_CRASH_HANDLER

クラッシュの処理およびレポートを無効化します (Boolean)

ネットワークの自動インスツルメンテーション

ネットワークの自動インスツルメンテーションでは、以下の追加設定を構成できます。

DD_DISABLE_HEADERS_INJECTION

トレースヘッダーのすべての挿入を無効化します (Boolean)

DD_INSTRUMENTATION_EXTRA_HEADERS

ログを作成する特定の追加ヘッダー (文字列リスト)

DD_EXCLUDED_URLS

ログの作成またはヘッダーの挿入を行わない URL (文字列リスト)

DD_ENABLE_RECORD_PAYLOAD

リクエストおよび応答内のペイロードのサブセット (1024 バイト) のレポートを有効化します (Boolean)

DD_MAX_PAYLOAD_SIZE

ペイロードから報告される最大サイズを設定します。デフォルトは 1024 (整数)

DD_DISABLE_NETWORK_CALL_STACK

ネットワークスパンのコールスタック情報を無効にします (ブール値)

DD_ENABLE_NETWORK_CALL_STACK_SYMBOLICATED

メソッド名だけでなく、正確なファイルや行の情報を含むコールスタック情報を表示します。テストのパフォーマンスに影響を与える可能性があります (ブール値)

インフラストラクチャーテストの相関

自身のインフラストラクチャーでテストを実行している場合 (macOS やシミュレータのテスト)、Datadog Agent をインストールして以下を設定することで、テストとインフラストラクチャーのメトリクスを関連付けることができます。

DD_CIVISIBILITY_REPORT_HOSTNAME

テストを開始するマシンのホスト名を報告します (ブール値)

モジュール DatadogSDKTesting をインポートしクラス: DDInstrumentationControl を使用することで、Swift または Objective-C の一部のテストで特定の自動インスツルメンテーションを有効/無効にすることも可能です。

カスタムタグ

環境変数

DD_TAGS 環境変数を（または以下で説明されているとおり Info.plist ファイルに）使用できます。スペース区切りの key:tag のペアを含む必要があります。例:

DD_TAGS=tag-key-0:tag-value-0 tag-key-1:tag-value-1

値の 1 つが $ の文字で始まる場合、同じ名前（存在する場合）の環境変数に置換されます。例:

DD_TAGS=home:$HOME

$ 文字を使うことで、値の先頭にある環境変数を置換することもサポートされます。ただし、その値には環境変数に対応しない文字 (a-z、A-Z または _) が含まれている必要があります。例:

FOO = BAR
DD_TAGS=key1:$FOO-v1 // expected: key1:BAR-v1

OpenTelemetry

注: OpenTelemetry の使用は Swift でのみサポートされています。

Datadog Swift テストフレームワークは、内部的に OpenTelemetry をトレーシングテクノロジーとして使用します。OpenTelemetry トレーサーには、DDInstrumentationControl.openTelemetryTracer を使用してアクセスでき、OpenTelemetry API を使用します。たとえば、タグまたは属性を追加するには、

import DatadogSDKTesting
import OpenTelemetryApi

let tracer = DDInstrumentationControl.openTelemetryTracer as? Tracer
let span = tracer?.spanBuilder(spanName: "ChildSpan").startSpan()
span?.setAttribute(key: "OTTag2", value: "OTValue2")
span?.end()

テストターゲットは、opentelemetry-swift で明示的にリンクする必要があります。

コードカバレッジを報告する

コードカバレッジが利用できる場合、Datadog SDK (v2.2.7+) は、テストセッションの test.code_coverage.lines_pct タグでそれを報告します。

Xcode では、Test Scheme でコードカバレッジの報告を有効にすることができます。

テストセッションの Coverage タブで、テストカバレッジの推移を見ることができます。

構成に Info.plist を使用する

または、環境変数を設定する代わりに、構成の値を（アプリバンドルではなく）テストバンドルの Info.plist ファイルに追加して提供することも可能です。環境変数と Info.plist ファイルに同じ設定がされている場合は、環境変数が優先されます。

CI プロバイダーの環境変数

手動テスト API

Swift プロジェクトで XCTests を使用している場合、DatadogSDKTestingフレームワークが自動的にインスツルメントし、Datadog バックエンドに結果を送信します。XCTest を使用しない場合、代わりに Swift/Objective-C の手動テスト API を使用することができ、これもバックエンドにテスト結果を報告します。

この API は、テストモジュール、テストスイート、テストの 3 つの概念に基づいています。

テストモジュール

テストモジュールは、テストを含むライブラリやバンドルの読み込みを表します。

テストモジュールを開始するには、DDTestModule.start() を呼び出して、テストするモジュールまたはバンドルの名前を渡します。

すべてのテストが終了したら、module.end() を呼び出し、これによりライブラリは残っているテスト結果をすべてバックエンドに送信します。

テストスイート

テストスイートは、共通の機能を共有するテストのセットで構成されます。これらのテストは、共通の初期化および終了を共有することができ、また、いくつかの変数を共有することができます。

module.suiteStart() を呼び出し、テストスイートの名前を渡すことでテストモジュール内にテストスイートを作成します。

スイートの中の関連するテストがすべて実行を終えたら suite.end() を呼び出します。

テスト

各テストはスイート内で実行され、pass、fail、skip のいずれかのステータスで終了する必要があります。テストは、オプションで属性やエラー情報などの追加情報を持つことができます。

suite.testStart() を呼び出し、テストの名前を渡すことで、スイート内のテストを作成します。テストが終了したら、定義済みのステータスのいずれかを設定する必要があります。

API インターフェイス

class DDTestModule {
    // モジュールを開始します。
    // - パラメーター:
    //   - bundleName: テストするモジュールまたはバンドルの名前。
    //   - startTime: オプション。モジュールが開始された時間。
    static func start(bundleName: String, startTime: Date? = nil) -> DDTestModule
    //
    // モジュールを終了します。
    // - パラメーター:
    //   - endTime: オプション。モジュールが終了した時間。
    func end(endTime: Date? = nil)
    // テストモジュールにタグ/属性を追加します。タグはいくつでも追加可能です。
    // - パラメーター:
    //   - key: タグの名前。同じ名前のタグが既に存在する場合、
    //     その値は新しい値で置き換えられます。
    //   - value: タグの値。数値または文字列を指定することができます。
    func setTag(key: String, value: Any)
    //
    // このモジュールでスイートを開始します。
    // - パラメーター:
    //   - name: スイートの名前。
    //   - startTime: オプション。スイートの開始時間。
    func suiteStart(name: String, startTime: Date? = nil) -> DDTestSuite
}
    //
public class DDTestSuite : NSObject {
    // テストスイートを終了します。
    // - パラメーター:
    //   - endTime: オプション。スイートが終了した時間。
    func end(endTime: Date? = nil)
    // タグ/属性をテストスイートに追加します。タグはいくつでも追加することができます。
    // - パラメーター:
    //   - key: タグの名前。同じ名前のタグが既に存在する場合、
    //     その値は新しい値で置き換えられます。
    //   - value: タグの値。数値または文字列を指定することができます。
    func setTag(key: String, value: Any)
    //
    // このスイートのテストを開始します。
    // - パラメーター:
    //   - name: テストの名前。
    //   - startTime: オプション。テストが開始された時間。
    func testStart(name: String, startTime: Date? = nil) -> DDTest
}
    //
public class DDTest : NSObject {
    // テストにタグ/属性を追加します。タグはいくつでも追加することができます。
    // - パラメーター:
    //   - key: タグの名前。同じ名前のタグが既に存在する場合、
    //     その値は新しい値で置き換えられます。
    //   - value: タグの値。数値または文字列を指定することができます。
    func setTag(key: String, value: Any)
    //
    // テストにエラー情報を追加します。1 つのテストが報告できるエラー情報は 1 つだけです。
    // - パラメーター:
    //   - type: 報告されるエラーのタイプ。
    //   - message: エラーに関連するメッセージ。
    //   - callstack: オプション。エラーに関連するコールスタック。
    func setErrorInfo(type: String, message: String, callstack: String? = nil)
    //
    // テストを終了します。
    // - パラメーター:
    //   - status: このテストについて報告されたステータス。
    //   - endTime: オプション。テストが終了した時間。
    func end(status: DDTestStatus, endTime: Date? = nil)
}
    //
// テストによって報告される可能性のあるステータス:
enum DDTestStatus {
  // テストは合格しました。
  case pass
  //
  // テストは失敗しました。
  case fail
  //
  // テストはスキップされました。
  case skip
}

コード例

次のコードは、API の簡単な使い方を表しています。

import DatadogSDKTesting
let module = DDTestModule.start(bundleName: "ManualModule")
let suite1 = module.suiteStart(name: "ManualSuite 1")
let test1 = suite1.testStart(name: "Test 1")
test1.setTag(key: "key", value: "value")
test1.end(status: .pass)
let test2 = suite1.testStart(name: "Test 2")
test2.SetErrorInfo(type: "Error Type", message: "Error message", callstack: "Optional callstack")
test2.end(test: test2, status: .fail)
suite1.end()
let suite2 = module.suiteStart(name: "ManualSuite 2")
..
..
module.end()

最後に必ず module.end() を呼び出し、すべてのテスト情報を Datadog に流すようにします。

ベストプラクティス

テストフレームワークと CI 表示を最大限に活用するために、以下のプラクティスに従ってください。

ビルド時にシンボルファイルを生成する

Xcode で DWARF with dSYM File (または swift でビルドする場合は -Xswiftc -debug-info-format=dwarf) を使用してコードをビルドします

テストフレームワークは、クラッシュのシンボル化、テストソースの位置の報告、コードの所有者の報告など、いくつかの機能でシンボルファイルを使用します。デバッグシンボルがバイナリに埋め込まれている場合、シンボルファイルを自動的に生成しますが、読み込みに余分な時間がかかることがあります。

macOS の UI テストのサンドボックスを無効化する

一部の Xcode のバージョンでは、UI Test バンドルはデフォルトでサンドボックス付きでビルドされています。サンドボックスに付属する設定は、一部のシステムコマンドで xcrun を使ってテストフレームワークを実行することを妨げるので、それを無効にする必要があります。

UI Test ランナーバンドルに Entitlements を追加し、それらに App Sandbox = NO を追加してサンドボックスを無効にします。また、.entitlement ファイルを作成し、Signing Build Settings に追加することができます。このファイルには、以下の内容を含める必要があります。

<key>com.apple.security.app-sandbox</key>
 <false/>

その他の参考資料

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

テスト結果とパフォーマンスを確認するドキュメント Intelligent Test Runner でテストジョブを高速化するドキュメント CI Visibility のトラブルシューティングドキュメント