Instrumentierte Test-Suites

Instrumentierte Test-Suites verpacken Gerätetests in isolierte testApk-APKs außerhalb des Standardverzeichnisses src/androidTest/ Ihres Moduls. Konfigurieren Sie sie mit der DSL für Test-Suites des Android Gradle-Plug-ins (AGP), um UI-, Integrations- oder End-to-End-Prüfungen mit dedizierten Abhängigkeiten, Varianten und Geräte-Targetings zu trennen.

Voraussetzungen

Damit Sie Instrumentierungstests verwenden können, muss Ihr Projekt die folgenden Anforderungen erfüllen:

  • Android Studio Rabbit 3 Canary 3 oder höher
  • AGP 9.6.0-alpha03 oder höher
  • Gradle 9.7.1 oder höher und JDK 17 oder höher
  • Ein com.android.application- oder com.android.library-Modul
  • Ein Gerät oder Emulator, der über die Android Debug Bridge (ADB) verbunden ist, oder eine Build-verwaltete Gerätedefinition

Weitere Informationen zum Abgleich von Vorabversionen finden Sie unter Kompatibilität mit Vorabversionen des Android-Gradle-Plug-ins.

Instrumentierte Test-Suite einrichten

So fügen Sie einem App- oder Bibliotheksmodul eine instrumentierte Test-Suite hinzu:

Test-Suites aktivieren

Aktivieren Sie in der Datei gradle.properties Ihres Projekts die Unterstützung für die Test-Suite:

android.experimental.testSuiteSupport=true

Suite konfigurieren

Erstellen Sie in der build.gradle.kts-Datei Ihres Moduls eine Suite im testOptions.customSuites-Block mit den Blöcken testApk und useJunitEngine sowie den Enum-Werten AgpTestSuiteInputParameters:

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")
                    }
                }
            }
        }
    }
}

Das AGP konfiguriert die Test-Runner- und Paket-IDs für AndroidJUnitRunner automatisch, ohne Abhängigkeiten von der androidTestImplementation-Konfiguration zu übernehmen. Wenn Sie einen benutzerdefinierten Runner verwenden möchten, legen Sie das Attribut android:name für das Element instrumentation in der Datei src/{suiteName}/AndroidManifest.xml fest.

Tests erstellen

Legen Sie Ihre instrumentierten Tests im Verzeichnis {module}/src/{suiteName}/kotlin/ oder java/ ab, zusammen mit optionalen res/- oder assets/-Verzeichnissen oder einer AndroidManifest.xml-Datei. Erstellen Sie beispielsweise die Datei 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)
    }
}

Unit- und Instrumentierungstests kombinieren

Wenn Sie lokale JVM-Tests und instrumentierte Gerätetests in einer einzigen Gradle-Aufgabe ausführen möchten, deklarieren Sie sowohl den hostJar- als auch den testApk-Block in einer Suite. Platzieren Sie Hosttests im Verzeichnis src/{suiteName}/test/ und Gerätetests im Verzeichnis 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")
                }
            }
        }
    }
}

Tests ausführen und Abdeckung erfassen

Mit Gradle können Sie instrumentierte Suites ausführen, Testläufe filtern und Berichte zur Abdeckung erstellen.

Auf verbundenen oder Build-verwalteten Geräten ausführen

Führen Sie ein verbundenes Ziel auf jedem Online-adb-Gerät aus oder führen Sie ein Ziel aus, das mit dem Attribut targetDevices konfiguriert ist:

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

Instrumentierungstests filtern

Filtern Sie Tests mit der --tests-Option oder den AndroidJUnitRunner-Argumenten von Gradle:

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

Sie können AndroidJUnitRunner-Argumente auch in der Befehlszeile mit einem Projektattribut wie -Pandroid.testInstrumentationRunnerArguments.size=small übergeben. Wenn Sie Standardargumente für den Runner im Block useJunitEngine festlegen möchten, rufen Sie die Methode addInputProperty auf, z. B. addInputProperty("android-test.instrumentation-args", "size=small").

Codeabdeckung auf dem Gerät erfassen

Für die Codeabdeckung auf dem Gerät ist ein debugfähiger Build und ein Gerät mit Android 9 (API-Level 28) oder höher erforderlich. So erfassen Sie die Abdeckung für eine instrumentierte oder gemischte Suite:

  1. Legen Sie das Attribut android.experimental.androidTest.coverage.useOnDeviceAgent=true in Ihrer gradle.properties-Datei fest.
  2. Legen Sie für die Suite die Property codeCoverage auf true fest.
  3. Wenn mehrere Geräte verbunden sind, legen Sie mit der Umgebungsvariable ANDROID_SERIAL ein Zielgerät fest.

Weitere Informationen zu den Anforderungen für den Agenten finden Sie unter Berichte zur Codeabdeckung ansehen (mit On-Device-Agenten).

Berichte prüfen

Nach Abschluss eines Testlaufs generiert das AGP Ausgaben in den folgenden Pfaden:

  • HTML-Testbericht: {module}/build/reports/tests/{taskName}/index.html
  • JUnit-XML-Ergebnisse: {module}/build/test-results/{taskName}/
  • Gerätespezifische XML- und Logcat-Dateien: {module}/build/intermediates/{variant}/{taskName}/results/
  • Bericht zur Codeabdeckung: {module}/build/reports/coverage/{suiteName}/index.html