Swift テスト

互換性

対応言語:

• Swift >= 5.2
• Objective-C >= 2.0

対応プラットフォーム:

• iOS >= 11.0
• macOS >= 10.13
• tvOS >= 11.0

注: Swift Concurrency を使用している場合、非同期タスクの正確なスパン表現のために Xcode >= 13.2 が必要です。

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

テストスイートレベルの可視化は dd-sdk-swift-testing>=2.1.0 からのみサポートされます。

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.1.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 や Framework のリンクなどの他の方法と比較して、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

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

DD_SITE (必須)

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

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

Datadog は Git の情報を使ってテスト結果を可視化し、リポジトリ、ブランチ、コミットごとにグループ化します。Git メタデータは CI プロバイダー環境変数を使用して自動的に収集され、テストアプリケーションに転送する必要があります (完全なリストについては、以下のセクション CI プロバイダー環境変数を参照してください)。

シミュレーターでテストを実行すると、ローカルの .git フォルダーを使用して完全な Git メタデータが収集されます。この場合、Git 関連の環境変数を転送する必要はありません。

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

DD_GIT_REPOSITORY_URL

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

テストの実行

インストール後、通常どおりにテストを実行します。たとえば、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 の 3 つのステータスのうち 1 つで終了する必要があります。テストは、オプションで属性やエラー情報などの追加情報を持つことができます。

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

収集した情報

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

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

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

• 各テストでカバーされるファイル名と行数を含むコードカバレッジ情報。

その他の参考資料

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

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