Les suites de tests d'instrumentation empaquettent les tests d'appareil dans des APK testApk isolés en dehors du répertoire src/androidTest/ par défaut de votre module. Configurez-les avec le DSL des suites de tests du plug-in Android Gradle (AGP) pour séparer les vérifications de l'UI, de l'intégration ou de bout en bout avec des dépendances, des variantes et le ciblage par types d'appareil dédiés.
Conditions requises
Pour utiliser des suites de tests d'instrumentation, 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 - Un appareil ou un émulateur connecté via Android Debug Bridge (adb) ou une définition d'appareil géré par compilation
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 d'instrumentation
Pour ajouter une suite de tests d'instrumentation à un module d'application ou de bibliothèque, procédez comme suit :
Activer les suites de tests
Dans le fichier gradle.properties de votre projet, activez la prise en charge de la suite de tests :
android.experimental.testSuiteSupport=true
Configurer la suite
Dans le fichier build.gradle.kts de votre module, créez une suite dans le bloc testOptions.customSuites avec les blocs testApk et useJunitEngine, ainsi que les valeurs d'énumération AgpTestSuiteInputParameters :
import com.android.build.api.dsl.AgpTestSuiteInputParameters
android {
testOptions {
// Optional: define build-managed virtual devices and device groups.
managedDevices {
localDevices {
create("api34Atd") {
// Use a device profile from Android Studio.
device = "Pixel 6"
apiLevel = 34
systemImageSource = "aosp-atd"
}
}
groups {
create("ciPhones") {
targetDevices.add(allDevices.getByName("api34Atd"))
}
}
}
customSuites {
create("androidSuite") {
targetVariants += listOf("debug")
testApk {
dependencies {
implementation("junit:junit:4.13.2")
implementation("androidx.test.ext:junit:1.2.1")
implementation("androidx.test:runner:1.6.2")
}
}
useJunitEngine {
includeEngines += listOf("android-test-engine")
// Match the engine and listener versions to your AGP
// version.
enginesDependencies.add(
"com.android.tools.androidtest:" +
"android-test-engine:9.6.0-alpha03"
)
enginesDependencies.add(
"com.android.tools.androidtest:" +
"android-test-engine-result-listener:9.6.0-alpha03"
)
enginesDependencies.add(
"org.junit.platform:junit-platform-launcher:1.10.2"
)
inputs += listOf(
// Omit TESTED_APKS in com.android.library modules.
AgpTestSuiteInputParameters.TESTED_APKS,
AgpTestSuiteInputParameters.TEST_APKS,
AgpTestSuiteInputParameters.ADB_EXECUTABLE,
AgpTestSuiteInputParameters.AAPT2_EXECUTABLE,
)
}
targets {
// Runs on connected adb devices.
create("default")
// Optional: runs on build-managed devices or groups in
// targetDevices.
create("managed") {
targetDevices += listOf("ciPhones")
}
}
}
}
}
}
AGP configure automatiquement l'exécuteur de test AndroidJUnitRunner et les ID de package sans hériter des dépendances de la configuration androidTestImplementation. Pour utiliser un exécuteur personnalisé, définissez l'attribut android:name sur l'élément instrumentation dans votre fichier src/{suiteName}/AndroidManifest.xml.
Créer des tests
Placez vos tests d'instrumentation dans le répertoire {module}/src/{suiteName}/kotlin/ ou java/, ainsi que les répertoires facultatifs res/ ou assets/, ou un fichier AndroidManifest.xml. Par exemple, créez le fichier app/src/androidSuite/kotlin/com/example/myapp/AppContextSuiteTest.kt :
package com.example.myapp
import androidx.test.ext.junit.runners.AndroidJUnit4
import androidx.test.platform.app.InstrumentationRegistry
import org.junit.Assert.assertEquals
import org.junit.Test
import org.junit.runner.RunWith
@RunWith(AndroidJUnit4::class)
class AppContextSuiteTest {
@Test
fun useAppContext() {
val appContext =
InstrumentationRegistry.getInstrumentation().targetContext
assertEquals("com.example.myapp", appContext.packageName)
}
}
Combiner des tests unitaires et d'instrumentation
Pour exécuter des tests JVM locaux et des tests d'appareil instrumentés dans une seule tâche Gradle, déclarez les blocs hostJar et testApk dans une même suite. Placez les tests d'hôte dans le répertoire src/{suiteName}/test/ et les tests d'appareil dans le répertoire src/{suiteName}/androidTest/ :
import com.android.build.api.dsl.AgpTestSuiteInputParameters
android {
testOptions {
customSuites {
create("combinedSuite") {
targetVariants += listOf("debug")
hostJar {
dependencies {
implementation(
"org.junit.jupiter:junit-jupiter-api:5.10.2"
)
}
}
testApk {
dependencies {
implementation("junit:junit:4.13.2")
implementation("androidx.test.ext:junit:1.2.1")
implementation("androidx.test:runner:1.6.2")
}
}
useJunitEngine {
includeEngines += listOf(
"junit-jupiter",
"android-test-engine",
)
enginesDependencies.add(
"org.junit.jupiter:junit-jupiter-engine:5.10.2"
)
enginesDependencies.add(
"com.android.tools.androidtest:" +
"android-test-engine:9.6.0-alpha03"
)
enginesDependencies.add(
"com.android.tools.androidtest:" +
"android-test-engine-result-listener:9.6.0-alpha03"
)
enginesDependencies.add(
"org.junit.platform:junit-platform-launcher:1.10.2"
)
inputs += listOf(
// Omit TESTED_APKS in com.android.library modules.
AgpTestSuiteInputParameters.TESTED_APKS,
AgpTestSuiteInputParameters.TEST_APKS,
AgpTestSuiteInputParameters.ADB_EXECUTABLE,
AgpTestSuiteInputParameters.AAPT2_EXECUTABLE,
)
}
targets {
create("default")
}
}
}
}
}
Exécuter des tests et collecter la couverture
Utilisez Gradle pour exécuter des suites de tests d'instrumentation, filtrer les scénarios de test et générer des rapports de couverture.
Exécuter sur des appareils connectés ou gérés par la compilation
Exécutez une cible connectée sur chaque appareil adb en ligne ou exécutez une cible configurée avec la propriété targetDevices :
# Run on connected adb devices. ./gradlew :app:testDebugAndroidSuiteDefaultTestSuite# Run on the ciPhones build-managed device group. ./gradlew :app:testDebugAndroidSuiteManagedCiPhonesTestSuite
Filtrer les tests d'instrumentation
Filtrez les tests avec l'option --tests ou les arguments AndroidJUnitRunner de Gradle :
./gradlew :app:testDebugAndroidSuiteDefaultTestSuite \
--tests "com.example.myapp.AppContextSuiteTest.useAppContext"Vous pouvez également transmettre des arguments AndroidJUnitRunner sur la ligne de commande avec une propriété de projet telle que -Pandroid.testInstrumentationRunnerArguments.size=small. Pour définir les arguments d'exécuteur par défaut dans le bloc useJunitEngine, appelez la méthode addInputProperty, par exemple addInputProperty("android-test.instrumentation-args", "size=small").
Collecter la couverture de code sur l'appareil
La couverture de code sur l'appareil nécessite un build débogable et un appareil exécutant Android 9 (niveau d'API 28) ou version ultérieure. Pour collecter la couverture d'une suite instrumentée ou mixte, procédez comme suit :
- Définissez la propriété
android.experimental.androidTest.coverage.useOnDeviceAgent=truedans votre fichiergradle.properties. - Définissez la propriété
codeCoveragesurtruedans la suite. - Si plusieurs appareils sont connectés, ciblez un appareil avec la variable d'environnement
ANDROID_SERIAL.
Pour en savoir plus sur les exigences de l'agent, consultez Afficher les rapports de couverture de code (avec l'agent sur l'appareil).
Inspecter les rapports
Une fois l'exécution d'un test terminée, AGP génère des 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}/ - XML et logcat par appareil :
{module}/build/intermediates/{variant}/{taskName}/results/ - Rapport sur la couverture de code :
{module}/build/reports/coverage/{suiteName}/index.html