Le plug-in Android Gradle (AGP) vous permet d'organiser les tests en suites de tests nommées dans le bloc testOptions de votre module. Chaque suite définit ses propres ensembles de sources, dépendances, moteurs de test de la plate-forme JUnit et variantes de compilation cibles.
Pourquoi utiliser des suites de tests ?
Par défaut, un module Android fournit un ensemble de sources test pour les tests unitaires locaux et un ensemble de sources androidTest pour les tests d'instrumentation. Les suites de tests dissocient l'organisation des tests de ces deux ensembles de sources, ce qui vous permet d'effectuer les opérations suivantes :
- Séparez les tests par objectif : conservez les tests unitaires, Robolectric, d'UI, de capture d'écran et de sauvegarde dans des répertoires
src/{suiteName}/dédiés au lieu de les mélanger dans les répertoiressrc/test/ousrc/androidTest/. - Isoler les dépendances et les moteurs : configurez le chemin de classe de chaque suite et le moteur de test de la plate-forme JUnit sans ajouter de dépendances à votre application ni aux configurations
testImplementationetandroidTestImplementation. - Ciblez des variantes et des appareils spécifiques : sélectionnez des variantes de compilation et des appareils par suite afin que les vérifications rapides s'exécutent localement et que les suites plus longues s'exécutent en intégration continue.
Types de suites
AGP inclut des suites de tests intégrées pour les workflows spécialisés et l'interface AgpTestSuite pour les suites personnalisées. Le tableau suivant répertorie les types de suites disponibles :
| Type de suite | Conteneur DSL | Objectif |
|---|---|---|
| Suites de tests unitaires | testOptions.customSuites |
Exécutez des tests JUnit 5, JUnit 4 ou Robolectric sur la JVM locale avec le bloc hostJar. |
| Suites de tests d'instrumentation | testOptions.customSuites |
Exécutez des tests d'appareil sur des appareils connectés ou gérés par la compilation avec le bloc testApk et le moteur de test android-test-engine. |
| Tester des captures d'écran avec des suites de tests | testOptions.screenshotTests |
Affichez et comparez @PreviewTest aperçus Compose sur l'hôte. |
| Tests automatisés de sauvegarde et de restauration | testOptions.backupTests |
Vérifiez les données de l'application lors des transferts locaux, cloud et d'appareil à appareil. |
| Parcours pour Android Studio | testOptions.customSuites |
Exécutez des parcours utilisateur XML basés sur l'IA sur des appareils connectés. |
| Suite d'assets personnalisés ou mixtes | testOptions.customSuites |
Exécutez des définitions de test statiques avec un moteur personnalisé ou combinez les blocs hostJar, testApk et assets dans une suite. |
Conditions requises
Pour utiliser des suites de tests personnalisées, assurez-vous que votre projet répond aux exigences suivantes :
- Android Studio Rabbit 3 Canary 3 ou version ultérieure
- AGP 9.6.0-alpha03 ou version ultérieure
- Gradle 9.7.1 ou version ultérieure et JDK 17 ou version ultérieure
- Un module
com.android.applicationoucom.android.library
Les suites de tests ne sont pas compatibles avec les modules com.android.kotlin.multiplatform.library ou com.android.test. Pour en savoir plus sur la correspondance des versions preview, consultez Compatibilité avec les versions preview du plug-in Android Gradle.
Configurer une suite de tests personnalisée
Pour obtenir des guides de configuration par étapes, consultez Suites de tests unitaires et Suites de tests d'instrumentation. Pour définir votre propre suite personnalisée, activez d'abord les suites de tests dans le fichier gradle.properties de votre projet :
android.experimental.testSuiteSupport=true
Ensuite, déclarez une suite dans le bloc testOptions.customSuites du fichier build.gradle.kts de votre module. Spécifiez la propriété targetVariants, un ou plusieurs blocs sources, le bloc useJunitEngine et au moins une cible dans le bloc 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")
}
}
}
}
}
Dans une implémentation TestEngine personnalisée, utilisez la propriété TestSuiteExecutionClient.default pour lire les valeurs d'énumération AgpTestSuiteInputParameters et les constantes TestEngineInputProperty standards telles que SERIAL_IDS et RESULTS_DIR.
Répertoires d'ensembles de sources
La disposition du répertoire de chaque suite dépend de la déclaration d'un seul bloc source ou de la combinaison de plusieurs blocs sources. Le tableau suivant répertorie les chemins d'accès par défaut dans le répertoire {module}/src/{suiteName}/ :
| Bloc de source | Suite à source unique | Suite mixte |
|---|---|---|
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 |
Répertoire racine de la suite | assetsTest/ |
Ne réutilisez pas les noms d'ensembles de sources, de types de produit, de types de compilation ou de variantes intégrés tels que main, androidTest ou debug comme nom de suite.
Cibles de contrôle par variante
Pour activer ou désactiver une cible de suite pour des variantes spécifiques, configurez l'interface TestSuiteTargetBuilder via la propriété HasTestSuitesBuilder.suites dans le bloc beforeVariants :
androidComponents {
beforeVariants { variantBuilder ->
if (variantBuilder.buildType == "release") {
variantBuilder.suites["mySuite"]
?.targets
?.get("default")
?.enable = false
}
}
}
Exécuter des suites et inspecter des rapports
AGP crée une tâche Gradle pour chaque combinaison de variante, de suite et de cible. Le tableau suivant liste les modèles de tâches :
| Type de tâche | Convention de nommage | Exemple de commande |
|---|---|---|
| Cible de la suite standard | test{Variant}{SuiteName}{Target}TestSuite |
./gradlew :app:testDebugMySuiteDefaultTestSuite |
Cibler avec la propriété targetDevices |
test{Variant}{SuiteName}{Target}{Devices}TestSuite |
./gradlew :app:testDebugAndroidSuiteManagedCiPhonesTestSuite |
Mise à jour de la référence (requiresUpdateTask = true) |
update{Variant}{SuiteName}{Target}TestSuite |
./gradlew :app:updateDebugScreenshotTestDefaultTestSuite |
| Agrégation des rapports de module | testAllSuites |
./gradlew :app:testAllSuites |
| Agrégation de modules et de dépendances | testAllSuitesWithDependencies |
./gradlew :app:testAllSuitesWithDependencies |
Les tâches test, connectedCheck et check n'exécutent pas de suites personnalisées, sauf si vous les associez à la méthode withTestTaskProviders. Pour activer les tâches testAllSuites et testAllSuitesWithDependencies, définissez la propriété android.experimental.reportAggregationSupport=true dans votre fichier gradle.properties.
Chaque exécution de suite écrit les résultats aux emplacements suivants :
- Rapport de test HTML :
{module}/build/reports/tests/{taskName}/index.html - Résultats XML JUnit :
{module}/build/test-results/{taskName}/ - Rapport sur la couverture de code :
{module}/build/reports/coverage/{suiteName}/index.html - Rapports compilés :
{module}/build/reports/{aggregationTask}/test-report/index.htmletcoverage-report/index.html
Pour générer des rapports de couverture de code, définissez la propriété codeCoverage sur true dans la suite. Pour les suites de captures d'écran Compose, configurez la suite dans votre fichier build.gradle.kts avec testOptions.customSuites.named("{suiteName}") { codeCoverage = true }.
Limites et problèmes connus
Les suites de tests sont soumises aux limites suivantes :
- Intégration de l'IDE : la compatibilité d'Android Studio avec les suites de tests personnalisées n'est pas disponible. L'éditeur de code peut afficher des erreurs de référence non résolues dans les fichiers sources de la suite, même si votre compilation est correctement configurée. Créez et exécutez des suites de tests à partir de la ligne de commande à l'aide de Gradle.
- Mise en cache des tâches : les tâches de la suite de tests sont toujours réexécutées lorsqu'elles sont appelées et ne sont pas chargées à partir du cache de compilation Gradle. Les suites sans fichiers de test sont ignorées avec l'état
NO-SOURCE.