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

インストルメンテーション テストスイートは、モジュールのデフォルトの src/androidTest/ ディレクトリ外の、分離された testApk APK にデバイスのテストをパッケージ化します。Android Gradle プラグイン(AGP)のテストスイート DSL を使用して、専用の依存関係、バリアント、デバイス ターゲティングで UI、統合、エンドツーエンドのチェックを分離するように設定します。

要件

インストルメンテーション テストスイートを使用するには、プロジェクトが次の要件を満たしていることを確認してください。

  • Android Studio Rabbit 3 Canary 3 以降
  • AGP 9.6.0-alpha03 以降
  • Gradle 9.7.1 以降、JDK 17 以降
  • com.android.application または com.android.library モジュール
  • Android Debug Bridge(adb)またはビルド管理デバイス定義を介して接続されたデバイスまたはエミュレータ

プレビュー版の照合について詳しくは、Android Gradle プラグインのプレビュー版との互換性をご覧ください。

インストルメンテーション テストスイートをセットアップする

アプリまたはライブラリ モジュールにインストルメンテーション テストスイートを追加する手順は次のとおりです。

テストスイートを有効にする

プロジェクトの gradle.properties ファイルで、テストスイートのサポートを有効にします。

android.experimental.testSuiteSupport=true

スイートを構成する

モジュールの build.gradle.kts ファイルで、testApk ブロックと useJunitEngine ブロック、AgpTestSuiteInputParameters 列挙値を使用して、testOptions.customSuites ブロック内にスイートを作成します。

import com.android.build.api.dsl.AgpTestSuiteInputParameters

android {
    testOptions {
        // Optional: define build-managed virtual devices and device groups.
        managedDevices {
            localDevices {
                create("api34Atd") {
                    // Use a device profile from Android Studio.
                    device = "Pixel 6"
                    apiLevel = 34
                    systemImageSource = "aosp-atd"
                }
            }
            groups {
                create("ciPhones") {
                    targetDevices.add(allDevices.getByName("api34Atd"))
                }
            }
        }

        customSuites {
            create("androidSuite") {
                targetVariants += listOf("debug")

                testApk {
                    dependencies {
                        implementation("junit:junit:4.13.2")
                        implementation("androidx.test.ext:junit:1.2.1")
                        implementation("androidx.test:runner:1.6.2")
                    }
                }

                useJunitEngine {
                    includeEngines += listOf("android-test-engine")
                    // Match the engine and listener versions to your AGP
                    // version.
                    enginesDependencies.add(
                        "com.android.tools.androidtest:" +
                            "android-test-engine:9.6.0-alpha03"
                    )
                    enginesDependencies.add(
                        "com.android.tools.androidtest:" +
                            "android-test-engine-result-listener:9.6.0-alpha03"
                    )
                    enginesDependencies.add(
                        "org.junit.platform:junit-platform-launcher:1.10.2"
                    )

                    inputs += listOf(
                        // Omit TESTED_APKS in com.android.library modules.
                        AgpTestSuiteInputParameters.TESTED_APKS,
                        AgpTestSuiteInputParameters.TEST_APKS,
                        AgpTestSuiteInputParameters.ADB_EXECUTABLE,
                        AgpTestSuiteInputParameters.AAPT2_EXECUTABLE,
                    )
                }

                targets {
                    // Runs on connected adb devices.
                    create("default")
                    // Optional: runs on build-managed devices or groups in
                    // targetDevices.
                    create("managed") {
                        targetDevices += listOf("ciPhones")
                    }
                }
            }
        }
    }
}

AGP は、androidTestImplementation 構成から依存関係を継承することなく、AndroidJUnitRunner テストランナーとパッケージ ID を自動的に構成します。カスタム ランナーを使用するには、src/{suiteName}/AndroidManifest.xml ファイルの instrumentation 要素に android:name 属性を設定します。

テストを作成する

インストゥルメンテーション テストを {module}/src/{suiteName}/kotlin/ ディレクトリまたは java/ ディレクトリに配置します。必要に応じて、res/ ディレクトリ、assets/ ディレクトリ、AndroidManifest.xml ファイルも配置します。たとえば、app/src/androidSuite/kotlin/com/example/myapp/AppContextSuiteTest.kt ファイルを作成します。

package com.example.myapp

import androidx.test.ext.junit.runners.AndroidJUnit4
import androidx.test.platform.app.InstrumentationRegistry
import org.junit.Assert.assertEquals
import org.junit.Test
import org.junit.runner.RunWith

@RunWith(AndroidJUnit4::class)
class AppContextSuiteTest {
    @Test
    fun useAppContext() {
        val appContext =
            InstrumentationRegistry.getInstrumentation().targetContext
        assertEquals("com.example.myapp", appContext.packageName)
    }
}

単体テストとインストルメンテーション テストを組み合わせる

ローカル JVM テストとインストルメンテーション デバイス テストを単一の Gradle タスクで実行するには、1 つのスイートで hostJar ブロックと testApk ブロックの両方を宣言します。ホストテストは src/{suiteName}/test/ ディレクトリに、デバイス テストは src/{suiteName}/androidTest/ ディレクトリに配置します。

import com.android.build.api.dsl.AgpTestSuiteInputParameters

android {
    testOptions {
        customSuites {
            create("combinedSuite") {
                targetVariants += listOf("debug")

                hostJar {
                    dependencies {
                        implementation(
                            "org.junit.jupiter:junit-jupiter-api:5.10.2"
                        )
                    }
                }

                testApk {
                    dependencies {
                        implementation("junit:junit:4.13.2")
                        implementation("androidx.test.ext:junit:1.2.1")
                        implementation("androidx.test:runner:1.6.2")
                    }
                }

                useJunitEngine {
                    includeEngines += listOf(
                        "junit-jupiter",
                        "android-test-engine",
                    )
                    enginesDependencies.add(
                        "org.junit.jupiter:junit-jupiter-engine:5.10.2"
                    )
                    enginesDependencies.add(
                        "com.android.tools.androidtest:" +
                            "android-test-engine:9.6.0-alpha03"
                    )
                    enginesDependencies.add(
                        "com.android.tools.androidtest:" +
                            "android-test-engine-result-listener:9.6.0-alpha03"
                    )
                    enginesDependencies.add(
                        "org.junit.platform:junit-platform-launcher:1.10.2"
                    )

                    inputs += listOf(
                        // Omit TESTED_APKS in com.android.library modules.
                        AgpTestSuiteInputParameters.TESTED_APKS,
                        AgpTestSuiteInputParameters.TEST_APKS,
                        AgpTestSuiteInputParameters.ADB_EXECUTABLE,
                        AgpTestSuiteInputParameters.AAPT2_EXECUTABLE,
                    )
                }

                targets {
                    create("default")
                }
            }
        }
    }
}

テストを実行してカバレッジを収集する

Gradle を使用して、インストルメンテーション スイートの実行、テストケースのフィルタリング、カバレッジ レポートの生成を行います。

接続されたデバイスまたはビルド管理デバイスで実行する

オンラインのすべての adb デバイスで接続されたターゲットを実行するか、targetDevices プロパティで構成されたターゲットを実行します。

# Run on connected adb devices.
./gradlew :app:testDebugAndroidSuiteDefaultTestSuite
# Run on the ciPhones build-managed device group.
./gradlew :app:testDebugAndroidSuiteManagedCiPhonesTestSuite

インストルメンテーション テストをフィルタする

Gradle の --tests オプションまたは AndroidJUnitRunner 引数を使用してテストをフィルタします。

./gradlew :app:testDebugAndroidSuiteDefaultTestSuite \
    --tests "com.example.myapp.AppContextSuiteTest.useAppContext"

-Pandroid.testInstrumentationRunnerArguments.size=small などのプロジェクト プロパティを使用して、コマンドラインで AndroidJUnitRunner 引数を渡すこともできます。useJunitEngine ブロックでデフォルトのランナー引数を設定するには、addInputProperty メソッド(addInputProperty("android-test.instrumentation-args", "size=small") など)を呼び出します。

デバイス上のコード カバレッジを収集する

デバイス上のコード カバレッジには、デバッグ可能なビルドと、Android 9(API レベル 28)以降を搭載したデバイスが必要です。インストルメント化されたスイートまたは混合スイートのカバレッジを収集する手順は次のとおりです。

  1. gradle.properties ファイルで android.experimental.androidTest.coverage.useOnDeviceAgent=true プロパティを設定します。
  2. スイートの codeCoverage プロパティを true に設定します。
  3. 複数のデバイスが接続されている場合は、ANDROID_SERIAL 環境変数を使用して 1 つのデバイスをターゲットにします。

エージェントの要件の詳細については、コード カバレッジ レポートを表示する(オンデバイス エージェントを使用)をご覧ください。

レポートを検査する

テスト実行が完了すると、AGP は次のパスに出力を生成します。

  • HTML テストレポート: {module}/build/reports/tests/{taskName}/index.html
  • JUnit XML の結果: {module}/build/test-results/{taskName}/
  • デバイスごとの XML と logcat: {module}/build/intermediates/{variant}/{taskName}/results/
  • コード カバレッジ レポート: {module}/build/reports/coverage/{suiteName}/index.html