Android Gradle プラグインのテストスイート

Android Gradle プラグイン(AGP)を使用すると、モジュールの testOptions ブロックで、テストを名前付きテストスイートに整理できます。各スイートは、独自のソースセット、依存関係、JUnit プラットフォーム テストエンジン、ターゲット ビルド バリアントを定義します。

テストスイートを使用する理由

デフォルトでは、Android モジュールはローカル単体テスト用に 1 つの test ソースセット、インストルメンテーション テスト用に 1 つの androidTest ソースセットを提供します。テストスイートは、テストの編成をこれら 2 つのソースセットから切り離すことで、次のことを可能にします。

  • 目的別にテストを分ける: ユニットテスト、Robolectric テスト、UI テスト、スクリーンショット テスト、バックアップ テストを src/test/ ディレクトリや src/androidTest/ ディレクトリに混在させるのではなく、専用の src/{suiteName}/ ディレクトリに保存します。
  • 依存関係とエンジンを分離する: アプリや testImplementation 構成、androidTestImplementation 構成に依存関係を追加することなく、各スイートのクラスパスと JUnit Platform テストエンジンを構成します。
  • 特定のバリアントとデバイスをターゲットにする: スイートごとにビルド バリアントとデバイスを選択して、高速チェックをローカルで実行し、より長いスイートを継続的インテグレーションで実行します。

スイートのタイプ

AGP には、特殊なワークフロー用の組み込みテストスイートと、カスタム スイート用の AgpTestSuite インターフェースが含まれています。次の表に、使用可能なスイートタイプを示します。

スイートタイプ DSL コンテナ 目的
単体テストスイート testOptions.customSuites hostJar ブロックを使用して、ローカル JVM で JUnit 5、JUnit 4、または Robolectric のテストを実行します。
インストルメンテーション テストスイート testOptions.customSuites testApk ブロックと android-test-engine テストエンジンを使用して、接続されているデバイスまたはビルドで管理されたデバイスでデバイスのテストを実行します。
テストスイートを使用したスクリーンショット テスト testOptions.screenshotTests ホストで @PreviewTest Compose プレビューをレンダリングして比較します。
自動バックアップと復元のテスト testOptions.backupTests ローカル、クラウド、デバイス間の転送でアプリデータを確認します。
Android Studio のジャーニー testOptions.customSuites コネクテッド デバイスで AI 駆動の XML ユーザー ジャーニーを実行します。
カスタム アセットまたは混合スイート testOptions.customSuites カスタム エンジンを使用して静的テスト定義を実行するか、hostJar、testApk、assets ブロックを 1 つのスイートに結合します。

要件

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

  • Android Studio Rabbit 3 Canary 3 以降
  • AGP 9.6.0-alpha03 以降
  • Gradle 9.7.1 以降、JDK 17 以降
  • com.android.application または com.android.library モジュール

テストスイートは、com.android.kotlin.multiplatform.library モジュールまたは com.android.test モジュールではサポートされていません。プレビュー版の照合について詳しくは、Android Gradle プラグインのプレビュー版との互換性をご覧ください。

カスタム テストスイートを設定する

詳細な設定ガイドについては、単体テストスイートとインストゥルメント化テストスイートをご覧ください。独自のカスタム スイートを定義するには、まずプロジェクトの gradle.properties ファイルでテストスイートを有効にします。

android.experimental.testSuiteSupport=true

次に、モジュールの build.gradle.kts ファイルの testOptions.customSuites ブロックでスイートを宣言します。targetVariants プロパティ、1 つ以上のソースブロック、useJunitEngine ブロック、targets ブロック内の少なくとも 1 つのターゲットを指定します。

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

android {
    testOptions {
        customSuites {
            create("mySuite") {
                // Exact variant names to test, such as "debug" or "demoDebug".
                targetVariants += listOf("debug")

                // Add one or more blocks: hostJar {}, testApk {}, or assets {}.
                assets {}

                useJunitEngine {
                    includeEngines += listOf("my-custom-engine")
                    enginesDependencies.add(
                        "com.example:my-custom-junit-engine:1.0.0"
                    )
                    enginesDependencies.add(
                        "org.junit.platform:junit-platform-launcher:1.10.2"
                    )

                    // Request build and SDK artifacts read by your engine.
                    inputs += listOf(
                        AgpTestSuiteInputParameters.STATIC_FILES,
                        // Omit TESTED_APKS in com.android.library modules.
                        AgpTestSuiteInputParameters.TESTED_APKS,
                        AgpTestSuiteInputParameters.ADB_EXECUTABLE,
                    )
                }

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

カスタム TestEngine 実装内で、TestSuiteExecutionClient.default プロパティを使用して、AgpTestSuiteInputParameters 列挙値と、SERIAL_IDS や RESULTS_DIR などの標準の TestEngineInputProperty 定数を読み取ります。

ソースセット ディレクトリ

各スイートのディレクトリ レイアウトは、1 つのソースブロックを宣言するか、複数のソースブロックを組み合わせるかによって異なります。次の表に、{module}/src/{suiteName}/ ディレクトリのデフォルト パスを示します。

ソースブロック シングルソース スイート 混合スイート
hostJar kotlin/、java/、resources/ test/kotlin/、test/java/、test/resources/
testApk kotlin/、java/、res/、assets/、AndroidManifest.xml androidTest/kotlin/、androidTest/java/、androidTest/res/、androidTest/assets/、androidTest/AndroidManifest.xml
assets スイートのルート ディレクトリ assetsTest/

main、androidTest、debug などの組み込みのソースセット、フレーバー、ビルドタイプ、バリアント名をスイート名として再利用しないでください。

バリエーションごとのコントロール ターゲット

特定のバリアントに対してスイート ターゲットを有効または無効にするには、beforeVariants ブロックの HasTestSuitesBuilder.suites プロパティを介して TestSuiteTargetBuilder インターフェースを構成します。

androidComponents {
    beforeVariants { variantBuilder ->
        if (variantBuilder.buildType == "release") {
            variantBuilder.suites["mySuite"]
                ?.targets
                ?.get("default")
                ?.enable = false
        }
    }
}

スイートを実行してレポートを検査する

AGP は、バリアント、スイート、ターゲットの組み合わせごとに Gradle タスクを作成します。次の表に、タスクパターンを示します。

タスクタイプ 命名パターン コマンドの例
標準スイートのターゲット test{Variant}{SuiteName}{Target}TestSuite ./gradlew :app:testDebugMySuiteDefaultTestSuite
targetDevices プロパティでターゲットを設定する test{Variant}{SuiteName}{Target}{Devices}TestSuite ./gradlew :app:testDebugAndroidSuiteManagedCiPhonesTestSuite
ベースラインの更新(requiresUpdateTask = true) update{Variant}{SuiteName}{Target}TestSuite ./gradlew :app:updateDebugScreenshotTestDefaultTestSuite
モジュール レポートの集計 testAllSuites ./gradlew :app:testAllSuites
モジュールと依存関係の集約 testAllSuitesWithDependencies ./gradlew :app:testAllSuitesWithDependencies

test、connectedCheck、check の各タスクは、withTestTaskProviders メソッドで接続しない限り、カスタム スイートを実行しません。testAllSuites タスクと testAllSuitesWithDependencies タスクを有効にするには、gradle.properties ファイルで android.experimental.reportAggregationSupport=true プロパティを設定します。

各スイートの実行では、次の場所に出力が書き込まれます。

  • HTML テストレポート: {module}/build/reports/tests/{taskName}/index.html
  • JUnit XML の結果: {module}/build/test-results/{taskName}/
  • コード カバレッジ レポート: {module}/build/reports/coverage/{suiteName}/index.html
  • 集計レポート: {module}/build/reports/{aggregationTask}/test-report/index.html、coverage-report/index.html

コード カバレッジ レポートを生成するには、スイートで codeCoverage プロパティを true に設定します。Compose スクリーンショット スイートの場合は、testOptions.customSuites.named("{suiteName}") { codeCoverage = true } を使用して build.gradle.kts ファイルでスイートを構成します。

既知の問題と制限事項

テストスイートには次の制限があります。

  • IDE の統合: Android Studio では、カスタム テストスイートはサポートされていません。ビルドが正しく構成されている場合でも、コードエディタでスイートのソースファイルに未解決の参照エラーが表示されることがあります。代わりに、Gradle を使用してコマンドラインからテストスイートをビルドして実行します。
  • タスク キャッシュ: テストスイート タスクは、呼び出されると常に再実行され、Gradle ビルド キャッシュから読み込まれません。テストファイルのないスイートは、NO-SOURCE ステータスでスキップされます。