Il plug-in Android per Gradle (AGP) ti consente di organizzare i test in suite di test denominate nel blocco testOptions del modulo. Ogni suite definisce i propri set di risorse, le proprie dipendenze, i propri motori di test della piattaforma JUnit e le proprie varianti di build di destinazione.
Perché utilizzare le suite di test
Per impostazione predefinita, un modulo Android fornisce un set di risorse test per i test delle unità locali e un set di risorse androidTest per i test di instrumentazione. Le suite di test
disaccoppiano l'organizzazione dei test da questi due set di risorse in modo da poter eseguire
le seguenti operazioni:
- Separa i test in base allo scopo: conserva i test di unità, Robolectric, UI, screenshot e backup in directory
src/{suiteName}/dedicate anziché mescolarli nelle directorysrc/test/osrc/androidTest/. - Isola le dipendenze e i motori: configura il classpath di ogni suite e il motore di test della piattaforma JUnit senza aggiungere dipendenze alla tua app o alle configurazioni
testImplementationeandroidTestImplementation. - Scegli come target varianti di compilazione e dispositivi specifici: seleziona varianti di compilazione e dispositivi per suite in modo che i controlli rapidi vengano eseguiti localmente e le suite più lunghe vengano eseguite nell'integrazione continua.
Tipi di suite
AGP include suite di test integrate per workflow specializzati e l'interfaccia AgpTestSuite per suite personalizzate. La tabella seguente elenca i tipi di suite disponibili:
| Tipo di suite | Container DSL | Finalità |
|---|---|---|
| Suite di test delle unità | testOptions.customSuites |
Esegui test JUnit 5, JUnit 4 o Robolectric sulla JVM locale con il blocco hostJar. |
| Suite di test strumentati | testOptions.customSuites |
Esegui test dei dispositivi su dispositivi connessi o gestiti dalla build con il blocco testApk e il motore di test android-test-engine. |
| Test degli screenshot con suite di test | testOptions.screenshotTests |
Esegui il rendering e confronta @PreviewTest anteprime di Compose sull'host. |
| Test automatici di backup e ripristino | testOptions.backupTests |
Verifica i dati delle app nei trasferimenti locali, sul cloud e da dispositivo a dispositivo. |
| Percorsi per Android Studio | testOptions.customSuites |
Esegui user journey XML basati sull'AI sui dispositivi connessi. |
| Asset personalizzati o suite miste | testOptions.customSuites |
Esegui definizioni di test statici con un motore personalizzato o combina i blocchi hostJar, testApk e assets in un'unica suite. |
Requisiti
Per utilizzare le suite di test personalizzate, assicurati che il tuo progetto soddisfi i seguenti requisiti:
- Android Studio Rabbit 3 Canary 3 o versioni successive
- AGP 9.6.0-alpha03 o versioni successive
- Gradle 9.7.1 o versioni successive e JDK 17 o versioni successive
- Un modulo
com.android.applicationocom.android.library
Le suite di test non sono supportate nei moduli com.android.kotlin.multiplatform.library o com.android.test. Per saperne di più sulla corrispondenza delle versioni di anteprima, consulta Compatibilità con le anteprime del plug-in Android per Gradle.
Configura una suite di test personalizzata
Per guide alla configurazione passo passo, consulta Suite di test delle unità e Suite di test strumentati. Per definire la tua suite personalizzata, attiva prima le suite di test nel file gradle.properties del progetto:
android.experimental.testSuiteSupport=true
Poi, dichiara una suite nel blocco testOptions.customSuites del file build.gradle.kts del tuo modulo. Specifica la proprietà targetVariants, uno o più blocchi di origine, il blocco useJunitEngine e almeno una destinazione nel blocco targets:
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")
}
}
}
}
}
All'interno di un'implementazione TestEngine personalizzata, utilizza la proprietà TestSuiteExecutionClient.default per leggere i valori enum AgpTestSuiteInputParameters e le costanti TestEngineInputProperty standard come SERIAL_IDS e RESULTS_DIR.
Directory dei set di risorse
Il layout della directory di ogni suite dipende dal fatto che dichiari un blocco di origine o che combini più blocchi di origine. La tabella seguente elenca i percorsi predefiniti nella directory {module}/src/{suiteName}/:
| Blocco di origine | Suite con un'unica fonte | Suite mista |
|---|---|---|
hostJar |
kotlin/, java/ e 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 |
Directory root della suite | assetsTest/ |
Non riutilizzare i nomi di set di risorse, flavor, tipo di build o variante integrati, come
main, androidTest o debug, come nome della suite.
Target di controllo per variante
Per attivare o disattivare un target della suite per varianti specifiche, configura l'interfaccia TestSuiteTargetBuilder tramite la proprietà HasTestSuitesBuilder.suites nel blocco beforeVariants:
androidComponents {
beforeVariants { variantBuilder ->
if (variantBuilder.buildType == "release") {
variantBuilder.suites["mySuite"]
?.targets
?.get("default")
?.enable = false
}
}
}
Esegui suite e ispeziona i report
AGP crea un'attività Gradle per ogni combinazione di variante, suite e target. La tabella seguente elenca i pattern delle attività:
| Tipo di attività | Pattern di denominazione | Comando di esempio |
|---|---|---|
| Target suite standard | test{Variant}{SuiteName}{Target}TestSuite |
./gradlew :app:testDebugMySuiteDefaultTestSuite |
Target con la proprietà targetDevices |
test{Variant}{SuiteName}{Target}{Devices}TestSuite |
./gradlew :app:testDebugAndroidSuiteManagedCiPhonesTestSuite |
Aggiornamento della base di riferimento (requiresUpdateTask = true) |
update{Variant}{SuiteName}{Target}TestSuite |
./gradlew :app:updateDebugScreenshotTestDefaultTestSuite |
| Aggregazione dei report del modulo | testAllSuites |
./gradlew :app:testAllSuites |
| Aggregazione di moduli e dipendenze | testAllSuitesWithDependencies |
./gradlew :app:testAllSuitesWithDependencies |
Le attività test, connectedCheck e check non eseguono suite personalizzate, a meno che non le colleghi con il metodo withTestTaskProviders. Per attivare le attività testAllSuites e testAllSuitesWithDependencies, imposta la proprietà android.experimental.reportAggregationSupport=true nel file gradle.properties.
Ogni esecuzione della suite scrive gli output nelle seguenti posizioni:
- Report di test HTML:
{module}/build/reports/tests/{taskName}/index.html - Risultati XML JUnit:
{module}/build/test-results/{taskName}/ - Report sulla copertura del codice:
{module}/build/reports/coverage/{suiteName}/index.html - Report aggregati:
{module}/build/reports/{aggregationTask}/test-report/index.htmlecoverage-report/index.html
Per generare report sulla copertura del codice, imposta la proprietà codeCoverage su true nella suite. Per le suite di screenshot di Compose, configura la suite nel file build.gradle.kts con testOptions.customSuites.named("{suiteName}") { codeCoverage = true }.
Problemi noti e limitazioni
Le suite di test presentano le seguenti limitazioni:
- Integrazione con l'IDE: il supporto di Android Studio per le suite di test personalizzate non è disponibile. L'editor di codice potrebbe mostrare errori di riferimento non risolti nei file di origine della suite anche se la build è configurata correttamente. Crea ed esegui le suite di test dalla riga di comando utilizzando Gradle.
- Memorizzazione nella cache delle attività: le attività della suite di test vengono sempre eseguite di nuovo quando vengono richiamate e non vengono caricate dalla cache di build di Gradle. Le suite senza file di test vengono ignorate con lo stato
NO-SOURCE.