Suite di test nel plug-in Android per Gradle

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 directory src/test/ o src/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 testImplementation e androidTestImplementation.
  • 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.application o com.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.html e coverage-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.