Mit dem Android Gradle-Plug-in (AGP) können Sie Tests im testOptions-Block Ihres Moduls in benannten Test-Suites organisieren. Jede Suite definiert ihre eigenen Source-Sets, Abhängigkeiten, JUnit-Plattform-Test-Engines und Ziel-Build-Varianten.
Vorteile von Test-Suites
Standardmäßig bietet ein Android-Modul ein test-Source-Set für lokale Unittests und ein androidTest-Source-Set für Instrumentierungstests. Test-Suites entkoppeln die Testorganisation von diesen beiden Source-Sets, sodass Sie Folgendes tun können:
- Tests nach Zweck trennen: Speichern Sie Unit-, Robolectric-, UI-, Screenshot- und Sicherungstests in dedizierten
src/{suiteName}/-Verzeichnissen, anstatt sie in den Verzeichnissensrc/test/odersrc/androidTest/zu mischen. - Abhängigkeiten und Engines isolieren: Konfigurieren Sie den Klassenpfad und die JUnit-Plattform-Test-Engine jeder Suite, ohne Ihrer Anwendung oder den Konfigurationen
testImplementationundandroidTestImplementationAbhängigkeiten hinzuzufügen. - Auf bestimmte Varianten und Geräte ausrichten: Wählen Sie Build-Varianten und Geräte pro Suite aus, damit schnelle Prüfungen lokal und längere Suites in der Continuous Integration ausgeführt werden.
Suitetypen
Das AGP enthält integrierte Test-Suites für spezielle Workflows und die Schnittstelle AgpTestSuite für benutzerdefinierte Suites. In der folgenden Tabelle sind die verfügbaren Suite-Typen aufgeführt:
| Suite-Typ | DSL-Container | Zweck |
|---|---|---|
| Unit-Test-Suites | testOptions.customSuites |
Führen Sie JUnit 5-, JUnit 4- oder Robolectric-Tests auf der lokalen JVM mit dem Block hostJar aus. |
| Instrumentierte Test-Suites | testOptions.customSuites |
Führen Sie Gerätetests auf verbundenen oder Build-verwalteten Geräten mit dem testApk-Block und der android-test-engine-Test-Engine aus. |
| Screenshot-Tests mit Test-Suites | testOptions.screenshotTests |
@PreviewTest Compose-Vorschauen auf dem Host rendern und vergleichen. |
| Automatisierte Sicherungs- und Wiederherstellungstests | testOptions.backupTests |
App-Daten bei lokalen, Cloud- und Gerät-zu-Gerät-Übertragungen prüfen. |
| Abläufe für Android Studio | testOptions.customSuites |
KI-gestützte XML-User Journeys auf verbundenen Geräten ausführen |
| Benutzerdefinierte Assets oder gemischte Suites | testOptions.customSuites |
Führen Sie statische Testdefinitionen mit einer benutzerdefinierten Engine aus oder kombinieren Sie die Blöcke hostJar, testApk und assets in einer Suite. |
Voraussetzungen
Damit Sie benutzerdefinierte Test-Suites 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
Test-Suites werden in com.android.kotlin.multiplatform.library- oder com.android.test-Modulen nicht unterstützt. Weitere Informationen zum Abgleich von Vorabversionen finden Sie unter Kompatibilität mit Vorabversionen des Android-Gradle-Plug-ins.
Benutzerdefinierte Test-Suite einrichten
Eine detaillierte Anleitung zur Einrichtung finden Sie unter Unit-Test-Suites und Instrumentierte Test-Suites. Wenn Sie eine eigene benutzerdefinierte Suite definieren möchten, aktivieren Sie zuerst Test-Suites in der Datei gradle.properties Ihres Projekts:
android.experimental.testSuiteSupport=true
Deklarieren Sie als Nächstes eine Suite im testOptions.customSuites-Block der build.gradle.kts-Datei Ihres Moduls. Geben Sie das Attribut targetVariants, einen oder mehrere Quellblöcke, den Block useJunitEngine und mindestens ein Ziel im Block targets an:
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")
}
}
}
}
}
Verwenden Sie in einer benutzerdefinierten TestEngine-Implementierung das Attribut TestSuiteExecutionClient.default, um AgpTestSuiteInputParameters-Enum-Werte und Standard-TestEngineInputProperty-Konstanten wie SERIAL_IDS und RESULTS_DIR zu lesen.
Source-Set-Verzeichnisse
Das Verzeichnislayout jeder Suite hängt davon ab, ob sie einen einzelnen Quellblock deklariert oder mehrere Quellblöcke kombiniert. In der folgenden Tabelle sind die Standardpfade im Verzeichnis {module}/src/{suiteName}/ aufgeführt:
| Quellblock | Suite mit einer einzigen Quelle | Gemischte Suite |
|---|---|---|
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 |
Stammverzeichnis der Suite | assetsTest/ |
Verwenden Sie keine integrierten Source-Set-, Flavor-, Build-Typ- oder Variantennamen wie main, androidTest oder debug als Suite-Namen.
Kontrollziele pro Variante
Wenn Sie ein Suite-Ziel für bestimmte Varianten aktivieren oder deaktivieren möchten, konfigurieren Sie die Schnittstelle TestSuiteTargetBuilder über das Attribut HasTestSuitesBuilder.suites im Block beforeVariants:
androidComponents {
beforeVariants { variantBuilder ->
if (variantBuilder.buildType == "release") {
variantBuilder.suites["mySuite"]
?.targets
?.get("default")
?.enable = false
}
}
}
Suites ausführen und Berichte prüfen
Das AGP erstellt für jede Kombination aus Variante, Suite und Ziel eine Gradle-Aufgabe. In der folgenden Tabelle sind die Aufgabenmuster aufgeführt:
| Aufgabentyp | Namensmuster | Beispielbefehl |
|---|---|---|
| Standard-Suite-Ziel | test{Variant}{SuiteName}{Target}TestSuite |
./gradlew :app:testDebugMySuiteDefaultTestSuite |
Targeting mit dem Attribut targetDevices |
test{Variant}{SuiteName}{Target}{Devices}TestSuite |
./gradlew :app:testDebugAndroidSuiteManagedCiPhonesTestSuite |
Baseline-Update (requiresUpdateTask = true) |
update{Variant}{SuiteName}{Target}TestSuite |
./gradlew :app:updateDebugScreenshotTestDefaultTestSuite |
| Zusammenfassung von Modulberichten | testAllSuites |
./gradlew :app:testAllSuites |
| Modul- und Abhängigkeitsaggregation | testAllSuitesWithDependencies |
./gradlew :app:testAllSuitesWithDependencies |
Die Aufgaben test, connectedCheck und check führen keine benutzerdefinierten Suites aus, es sei denn, Sie verknüpfen sie mit der Methode withTestTaskProviders. Wenn Sie die Aufgaben testAllSuites und testAllSuitesWithDependencies aktivieren möchten, legen Sie das Attribut android.experimental.reportAggregationSupport=true in der Datei gradle.properties fest.
Bei jeder Suite-Ausführung werden Ausgaben an die folgenden Speicherorte geschrieben:
- HTML-Testbericht:
{module}/build/reports/tests/{taskName}/index.html - JUnit-XML-Ergebnisse:
{module}/build/test-results/{taskName}/ - Bericht zur Codeabdeckung:
{module}/build/reports/coverage/{suiteName}/index.html - Zusammengefasste Berichte:
{module}/build/reports/{aggregationTask}/test-report/index.htmlundcoverage-report/index.html
Wenn Sie Berichte zur Codeabdeckung erstellen möchten, setzen Sie das Attribut codeCoverage in der Suite auf true. Konfigurieren Sie für Compose-Screenshot-Suites die Suite in Ihrer build.gradle.kts-Datei mit testOptions.customSuites.named("{suiteName}") { codeCoverage = true }.
Bekannte Probleme und Beschränkungen
Für Test-Suites gelten die folgenden Einschränkungen:
- IDE-Integration: Die Unterstützung von benutzerdefinierten Test-Suites in Android Studio ist nicht verfügbar. Im Code-Editor werden möglicherweise nicht aufgelöste Referenzfehler in Suite-Quelldateien angezeigt, auch wenn Ihr Build richtig konfiguriert ist. Erstellen und führen Sie Test-Suites stattdessen über die Befehlszeile mit Gradle aus.
- Aufgaben-Caching: Test-Suite-Aufgaben werden beim Aufruf immer noch einmal ausgeführt und nicht aus dem Gradle-Build-Cache geladen. Suites ohne Testdateien werden mit dem Status
NO-SOURCEübersprungen.