Test-Suites im Android-Gradle-Plug-in

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 Verzeichnissen src/test/ oder src/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 testImplementation und androidTestImplementation Abhä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- oder com.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.html und coverage-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.