Suites de tests unitaires

Les suites de tests unitaires exécutent des tests JVM locaux dans des ensembles de sources hostJar isolés en dehors du répertoire src/test/ par défaut de votre module. Configurez-les avec le DSL des suites de tests du plug-in Android Gradle (AGP) pour isoler les tests JUnit 5, JUnit 4 ou Robolectric par variante.

Conditions requises

Pour utiliser des suites de tests unitaires, 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

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 unitaires

Pour ajouter une suite de tests unitaires à 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 hostJar et useJunitEngine :

android {
    testOptions {
        customSuites {
            create("unitSuite") {
                // Exact variant names to test, such as "debug" or "demoDebug".
                targetVariants += listOf("debug")

                hostJar {
                    dependencies {
                        // JUnit 5 API for @org.junit.jupiter.api.Test.
                        implementation(
                            "org.junit.jupiter:junit-jupiter-api:5.10.2"
                        )
                        // Optional: JUnit 4 API for @org.junit.Test.
                        implementation("junit:junit:4.13.2")
                    }
                }

                useJunitEngine {
                    // Add "junit-jupiter" (JUnit 5), "junit-vintage" (JUnit 4),
                    // or both.
                    includeEngines += listOf("junit-jupiter", "junit-vintage")
                    enginesDependencies.add(
                        "org.junit.jupiter:junit-jupiter-engine:5.10.2"
                    )
                    enginesDependencies.add(
                        "org.junit.vintage:junit-vintage-engine:5.10.2"
                    )
                    enginesDependencies.add(
                        "org.junit.platform:junit-platform-launcher:1.10.2"
                    )
                }

                targets {
                    create("default")
                }
            }
        }
    }
}

Votre suite accède automatiquement aux classes et aux dépendances de la variante cible sans hériter des dépendances de la configuration testImplementation.

Créer des tests

Placez vos tests unitaires dans le répertoire {module}/src/{suiteName}/kotlin/ ou java/, et les ressources de test Java dans le répertoire {module}/src/{suiteName}/resources/. Par exemple, créez le fichier app/src/unitSuite/kotlin/com/example/myapp/CalculatorSuiteTest.kt :

package com.example.myapp

import org.junit.jupiter.api.Assertions.assertEquals
import org.junit.jupiter.api.Test

class CalculatorSuiteTest {
    @Test
    fun addition_isCorrect() {
        assertEquals(4, 2 + 2)
    }
}

Inclure les ressources Android et Robolectric

Pour accéder aux ressources, éléments, fichiers manifestes et classes R Android fusionnés, par exemple pour les tests Robolectric, définissez la propriété enableAndroidResources de l'interface TestSuiteHostJarSpec sur true :

android {
    testOptions {
        customSuites {
            create("roboSuite") {
                targetVariants += listOf("debug")

                hostJar {
                    enableAndroidResources = true
                    dependencies {
                        implementation("junit:junit:4.13.2")
                        implementation("org.robolectric:robolectric:4.14.1")
                        implementation("androidx.test:core-ktx:1.6.1")
                    }
                }

                useJunitEngine {
                    includeEngines += listOf("junit-vintage")
                    enginesDependencies.add(
                        "org.junit.vintage:junit-vintage-engine:5.10.2"
                    )
                    enginesDependencies.add(
                        "org.junit.platform:junit-platform-launcher:1.10.2"
                    )
                }

                targets {
                    create("default")
                }
            }
        }
    }
}

Personnaliser les tâches et la couverture

Activez la couverture JaCoCo sur une suite avec la propriété codeCoverage. Pour personnaliser les options Gradle Test par cible, transmettez une lambda de configuration à la méthode AgpTestSuiteTarget.configureTestTasks, qui fournit une instance TestTaskContext. Pour associer des tâches de validation à la tâche check, utilisez la méthode withTestTaskProviders :

android {
    testOptions {
        customSuites {
            named("unitSuite") {
                // Generates JaCoCo HTML and XML coverage reports.
                codeCoverage = true

                targets.named("default") {
                    configureTestTasks { context ->
                        systemProperty("suite.variant", context.targetedVariant)
                        maxParallelForks = 2
                    }
                }

                withTestTaskProviders { context ->
                    if (!context.isUpdateTask) {
                        tasks.named("check") {
                            dependsOn(this@withTestTaskProviders)
                        }
                    }
                }
            }
        }
    }
}

Pour appliquer les paramètres de tâche Test à toutes les cibles d'une suite, appelez plutôt la méthode AgpTestSuite.configureTestTasks sur la suite.

Exécuter des tests et inspecter les rapports

Exécutez votre suite à partir de la ligne de commande avec la tâche test{Variant}{SuiteName}{Target}TestSuite générée :

./gradlew :app:testDebugUnitSuiteDefaultTestSuite

Pour exécuter une seule classe ou méthode de test, transmettez l'option --tests de Gradle :

./gradlew :app:testDebugUnitSuiteDefaultTestSuite \
    --tests "com.example.myapp.CalculatorSuiteTest.addition_isCorrect"

Une fois l'exécution d'un test terminée, AGP génère des rapports aux emplacements suivants :

  • Rapport de test HTML : {module}/build/reports/tests/{taskName}/index.html
  • Résultats XML JUnit : {module}/build/test-results/{taskName}/
  • Rapport de couverture JaCoCo : {module}/build/reports/coverage/{suiteName}/index.html