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- odercom.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:
- Legen Sie das Attribut
android.experimental.androidTest.coverage.useOnDeviceAgent=truein Ihrergradle.properties-Datei fest. - Legen Sie für die Suite die Property
codeCoverageauftruefest. - Wenn mehrere Geräte verbunden sind, legen Sie mit der Umgebungsvariable
ANDROID_SERIALein 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