Cette page a été traduite par l'API Cloud Translation.

Test de capture d'écran de l'aperçu Compose

Les tests de capture d'écran sont un moyen efficace de vérifier l'apparence de votre UI pour les utilisateurs. L'outil de test de capture d'écran Compose Preview combine la simplicité et les fonctionnalités des aperçus composables avec les gains de productivité liés à l'exécution de tests de capture d'écran côté hôte. Les tests de capture d'écran Compose Preview sont conçus pour être aussi faciles à utiliser que les aperçus composables.

Un test de capture d'écran est un test automatisé qui prend une capture d'écran d'une partie de l'UI, puis la compare à une image de référence approuvée précédemment. Si les images ne correspondent pas, le test échoue et génère un rapport HTML pour vous aider à comparer et à trouver les différences.

Avec l'outil de test de capture d'écran d'aperçu Compose, vous pouvez :

Utilisez @PreviewTest pour créer des tests de capture d'écran pour les aperçus composables existants ou nouveaux.
Générez des images de référence à partir de ces aperçus composables.
Générez un rapport HTML qui identifie les modifications apportées à ces aperçus après avoir modifié le code.
Utilisez les paramètres @Preview, tels que uiMode ou fontScale, et les aperçus multiples pour vous aider à faire évoluer vos tests.
Modularisez vos tests avec le nouvel ensemble de sources screenshotTest.

Conditions requises

Pour utiliser les tests de capture d'écran de l'aperçu Compose, vous devez disposer des éléments suivants :

Plug-in Android Gradle 8.5.0-beta01 ou version ultérieure.
Kotlin 1.9.20 ou version ultérieure. Nous vous recommandons d'utiliser Kotlin 2.0 ou version ultérieure pour pouvoir utiliser le plug-in Gradle du compilateur Compose.
JDK 23 ou version antérieure. Cet outil n'est pas compatible avec JDK 24 ni les versions ultérieures en raison d'une dépendance vis-à-vis du gestionnaire de sécurité Java, qui a été supprimé dans les versions plus récentes de JDK.
Compose est activé pour votre projet. Nous vous recommandons d'activer Compose à l'aide du plug-in Gradle Compose Compiler.

Remarque : Si vous ne pouvez pas utiliser le plug-in Gradle du compilateur Compose, vous pouvez activer Compose en déclarant une dépendance directement sur le compilateur Compose. Assurez-vous d'utiliser la version 1.5.4 ou ultérieure de kotlinCompilerExtensionVersion.

Configuration

Pour activer l'outil, procédez comme suit :

Ajoutez le plug-in com.android.compose.screenshot, version 0.0.1-alpha10, à votre projet.

Ajoutez le plug-in à votre fichier de catalogues de versions :

[versions]
agp = "8.11.0-alpha06"
kotlin = "2.1.20"
screenshot = "0.0.1-alpha10"

[plugins]
screenshot = { id = "com.android.compose.screenshot", version.ref = "screenshot"}

Dans le fichier build.gradle.kts au niveau du module, ajoutez le plug-in dans le bloc plugins {} :
```
plugins {
    alias(libs.plugins.screenshot)
}
```

Activez la propriété expérimentale dans le fichier gradle.properties de votre projet.
```
android.experimental.enableScreenshotTest=true
```
Dans le bloc android {} de votre fichier build.gradle.kts au niveau du module, activez l'option expérimentale pour utiliser l'ensemble de sources screenshotTest.
```
android {
    experimentalProperties["android.experimental.enableScreenshotTest"] = true
}
```

Ajoutez les dépendances screenshot-validation-api et ui-tooling.

Ajoutez-les à vos catalogues de versions :

[libraries]
screenshot-validation-api = { group = "com.android.tools.screenshot", name = "screenshot-validation-api", version.ref = "screenshot"}
androidx-ui-tooling = { group = "androidx.compose.ui", name = "ui-tooling"}

Ajoutez-les à votre fichier build.gradle.kts au niveau du module :

dependencies {
  screenshotTestImplementation(libs.screenshot.validation.api)
  screenshotTestImplementation(libs.androidx.ui.tooling)
}

Désigner les aperçus composables à utiliser pour les tests de captures d'écran

Pour désigner les aperçus composables que vous souhaitez utiliser pour les tests de capture d'écran, marquez-les avec l'annotation @PreviewTest. Les aperçus doivent se trouver dans le nouvel ensemble de sources screenshotTest, par exemple app/src/screenshotTest/kotlin/com/example/yourapp/ExamplePreviewScreenshotTest.kt.

Vous pouvez ajouter d'autres composables et/ou aperçus, y compris des aperçus multiples, dans ce fichier ou dans d'autres fichiers créés dans le même ensemble de sources.

package com.example.yourapp

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

@PreviewTest
@Preview(showBackground = true)
@Composable
fun GreetingPreview() {
    MyApplicationTheme {
        Greeting("Android!")
    }
}

Générer des images de référence

Une fois que vous avez configuré une classe de test, vous devez générer des images de référence pour chaque aperçu. Ces images de référence servent à identifier les modifications ultérieurement, après avoir modifié le code. Pour générer des images de référence pour vos tests de capture d'écran d'aperçu composable, exécutez la tâche Gradle suivante :

Linux et macOS : ./gradlew updateDebugScreenshotTest (./gradlew :{module}:update{Variant}ScreenshotTest)
Windows : gradlew updateDebugScreenshotTest (gradlew :{module}:update{Variant}ScreenshotTest)

Une fois la tâche terminée, recherchez les images de référence dans app/src/screenshotTestDebug/reference ({module}/src/screenshotTest{Variant}/reference).

Générer un rapport de test

Une fois les images de référence existantes, exécutez la tâche de validation pour prendre une nouvelle capture d'écran et la comparer à l'image de référence :

Linux et macOS : ./gradlew validateDebugScreenshotTest (./gradlew :{module}:validate{Variant}ScreenshotTest)
Windows : gradlew validateDebugScreenshotTest (gradlew :{module}:validate{Variant}ScreenshotTest)

La tâche de validation crée un rapport HTML à l'adresse {module}/build/reports/screenshotTest/preview/{variant}/index.html.

Problèmes connus

Vous trouverez la liste actuelle des problèmes connus dans le composant de suivi des problèmes de l'outil. Signalez tout autre commentaire ou problème via l'outil de suivi des problèmes.

Mises à jour des versions

Notes de version et modifications pour les versions en cours.

0.0.1-alpha10

Cette version inclut les nouveautés suivantes :

À partir de cette version, vous devez marquer toutes vos fonctions d'aperçu avec l'annotation @PreviewTest. Les aperçus sans annotation ne seront pas exécutés.
Le répertoire des images de référence est passé de {module}/src/{variant}/screenshotTest/reference à {module}/src/screenshotTest{Variant}/reference. Cela permet de s'assurer que les images de référence générées ne font pas partie du code de production et d'être en phase avec la structure des répertoires des autres types de tests.
La tâche {variant}PreviewScreenshotRender est supprimée. Le rendu d'image est migré vers JUnit Test Engine.
La tâche update{Variant}ScreenshotTest compare les nouvelles images de rendu aux images de référence avant la mise à jour. Il ne met à jour que les images dont les différences sont supérieures à un seuil spécifié. L'indicateur de ligne de commande --updateFilter a été supprimé.

0.0.1-alpha06

Cette version inclut les nouveautés suivantes :

Seuil de différence d'image : ce nouveau paramètre de seuil global vous permettra de contrôler plus précisément les comparaisons de captures d'écran. Pour configurer, mettez à jour le fichier build.gradle.kts de votre module :

android {
    testOptions {
        screenshotTests {
            imageDifferenceThreshold = 0.0001f // 0.01%
        }
    }
}

Ce seuil s'appliquera à tous les tests de capture d'écran définis dans le module.

Correction de bugs : correction de certains bugs du moteur de rendu Compose et ajout de la compatibilité avec Compose vide
Améliorations des performances : l'algorithme de comparaison d'images a été mis à jour pour être plus rapide.