Suites de tests instrumentés

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.application ou com.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 :

  1. Définissez la propriété android.experimental.androidTest.coverage.useOnDeviceAgent=true dans votre fichier gradle.properties.
  2. Définissez la propriété codeCoverage sur true dans la suite.
  3. 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