Tests de capture d'écran avec des suites de tests

À partir du plug-in Android Gradle (AGP) 9.5.0-alpha03 et du moteur de test de capture d'écran Compose Preview 0.0.1-alpha16, le test de capture d'écran est intégré au framework natif suites de tests d'AGP.

Cette approche remplace le plug-in de capture d'écran autonome (com.android.compose.screenshot). Nous vous recommandons d'adopter les suites de tests AGP pour les raisons suivantes :

• Cycle de vie des tâches Gradle natives : les tests de capture d'écran s'intègrent directement aux cycles de vie des tests Gradle et AGP standards, ce qui améliore l'isolation des tâches et la fiabilité de l'exécution des tests.
• Prise en charge des suites multivariantes et personnalisées : vous pouvez créer plusieurs suites de tests de capture d'écran distinctes (telles que screenshotTest, uiTests ou smokeTests) dans un même module et cibler des variantes de compilation spécifiques (telles que demoDebug ou release), au lieu d'être limité à un seul ensemble de sources préconfiguré.
• Performances et isolation de compilation améliorées : les suites de tests AGP utilisent des transformations d'artefacts intégrées (telles que l'extraction du runtime Layoutlib) et le chargement de classes isolées, avec une compatibilité totale avec la mise en cache de la configuration Gradle et l'isolation des projets.

Conditions requises

Pour utiliser Compose Screenshot Testing avec des suites de tests, assurez-vous que votre environnement répond aux exigences suivantes :

• Android Studio Rabbit 1 Canary 4 ou version ultérieure.
• Plug-in Android Gradle (AGP) version 9.5.0-alpha03 ou ultérieure.
• Compose Screenshot Engine version 0.0.1-alpha16 ou ultérieure.
• JDK version 17 ou ultérieure.
• Compose est activé pour votre projet. Nous vous recommandons d'activer Compose à l'aide du plug-in Gradle Compose Compiler.

Configuration

Pour configurer les tests de capture d'écran Compose avec des suites de tests, procédez comme suit :

1. Activer les indicateurs expérimentaux

Dans le fichier gradle.properties racine de votre projet, activez les tests de capture d'écran et la prise en charge des suites de tests :

android.experimental.enableScreenshotTest=true
android.experimental.testSuiteSupport=true

2. Configurer la suite de tests dans le fichier build.gradle.kts

Dans le fichier build.gradle.kts de votre module, définissez une suite de tests de capture d'écran dans le bloc testOptions :

android {
    testOptions {
        screenshotTests.create("screenshotTest") { // suiteName can be customized (for example, "uiTests")
            engineVersion = "0.0.1-alpha16"
            targetVariants.add("demoDebug") // Add specific variants to test

            dependencies {
                implementation(libs.androidx.compose.ui.tooling)
                implementation("com.android.tools.screenshot:screenshot-validation-api:0.0.1-alpha16")
            }
        }
    }
}

3. Créer l'ensemble de sources de test

Créez un répertoire d'ensemble de sources dédié correspondant au nom de votre suite :

{module}/src/{suiteName}/kotlin/

Par exemple, pour une suite nommée screenshotTest :

feature/foryou/impl/src/screenshotTest/kotlin/com/example/app/ForYouScreenTest.kt

4. Définir des tests d'aperçu composables

Annotez les composables avec @PreviewTest et les annotations standards @Preview ou multi-aperçu :

package com.example.app

import androidx.compose.runtime.Composable
import androidx.compose.ui.tooling.preview.Preview
import com.android.tools.screenshot.PreviewTest
import com.example.app.ui.theme.AppTheme

@PreviewTest
@Preview(showBackground = true)
@Composable
fun ForYouScreenPreview() {
    AppTheme {
        ForYouScreen(isSyncing = false)
    }
}

Exécuter des tests de capture d'écran

Les suites de tests AGP génèrent des tâches Gradle dédiées en fonction du nom, de la cible et des variantes de votre suite.

1. Générer ou mettre à jour des images de référence

Affichez les aperçus composables et stockez les images de référence de base de référence :

• Linux et macOS : ./gradlew update{SuiteName}{Target}{Variant}TestSuite (par exemple, ./gradlew updateScreenshotTestDefaultDemoDebugTestSuite)
• Windows : gradlew updateScreenshotTestDefaultDemoDebugTestSuite

Les images de référence sont générées et enregistrées à l'emplacement suivant :

{module}/src/{suiteName}{Target}{Variant}/reference/

2. Vérifier et exécuter des tests

Générez de nouvelles captures d'écran et comparez-les aux images de référence :

• Linux et macOS : ./gradlew test{SuiteName}{Target}{Variant}TestSuite (par exemple, ./gradlew testScreenshotTestDefaultDemoDebugTestSuite)
• Windows : gradlew testScreenshotTestDefaultDemoDebugTestSuite

Inspecter les rapports de test

Si des différences sont détectées ou si des tests échouent, AGP génère un rapport de test HTML.

• Emplacement du rapport :{module}/build/reports/tests/{taskName}/index.html (par exemple,app/build/reports/tests/testScreenshotTestDefaultDemoDebugTestSuite/index.html)

Le rapport mis à jour inclut les éléments suivants :

• Fiche de métadonnées de l'en-tête : affiche le nom du test, la méthode d'aperçu, la variante, la suite et le badge d'état.
• Catégorisation des erreurs : signale clairement les erreurs Reference Image Missing, Image Size Mismatch ou Pixel Mismatch avec des traces de pile copiables.
• Diff visuel dynamique : met en évidence les modifications subtiles avec une intensité plus faible et les modifications majeures avec un contraste élevé pour éviter l'avalement d'éléments imbriqués.

Migrer depuis l'ancien plug-in autonome

Pour migrer de l'ancien plug-in de capture d'écran autonome vers les suites de tests AGP, mettez à jour votre configuration Gradle et vos commandes de tâches.

Comparaison des DSL de configuration de compilation

Ancien plug-in autonome (obsolète)

// In build.gradle.kts
plugins {
    alias(libs.plugins.screenshot)
}

dependencies {
    screenshotTestImplementation(libs.androidx.compose.ui.tooling)
    screenshotTestImplementation("com.android.tools.screenshot:screenshot-validation-api:0.0.1-alpha16")
}

Suites de tests AGP (recommandé)

// In build.gradle.kts
android {
    testOptions {
        screenshotTests.create("screenshotTest") {
            engineVersion = "0.0.1-alpha16"
            targetVariants.add("demoDebug")

            dependencies {
                implementation(libs.androidx.compose.ui.tooling)
                implementation("com.android.tools.screenshot:screenshot-validation-api:0.0.1-alpha16")
            }
        }
    }
}

Mappage des tâches et des chemins