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 de l'aperçu Compose sont conçus pour être aussi simples à 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 et la compare ensuite à 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.

L'outil de test de capture d'écran d'aperçu Compose vous permet de :

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.

Intégration de l'IDE

Bien que vous puissiez utiliser l'outil de test de capture d'écran Compose Preview en exécutant manuellement les tâches Gradle sous-jacentes (updateScreenshotTest et validateScreenshotTest), la mise à jour groupée Canary 4 d'Android Studio Otter 3 introduit une intégration complète de l'IDE. Cela vous permet de générer des images de référence, d'exécuter des tests et d'analyser les échecs de validation entièrement dans l'IDE. Voici quelques-unes des principales fonctionnalités :

Icônes dans la marge de l'éditeur. Vous pouvez désormais exécuter des tests ou mettre à jour des images de référence directement à partir du code source. Des icônes d'exécution vertes s'affichent dans la marge à côté des composables et des classes annotés avec @PreviewTest.
- Exécuter des tests de capture d'écran. Exécutez des tests spécifiquement pour une seule fonction ou pour une classe entière.
- Ajoutez ou modifiez des images de référence. Déclenchez le flux de mise à jour spécifiquement pour le champ d'application sélectionné.

Gestion interactive des références : La mise à jour des images de référence est désormais plus sûre et plus précise.
- Boîte de dialogue "Générer une image de référence" Au lieu d'exécuter une tâche Gradle groupée, une nouvelle boîte de dialogue vous permet de visualiser et de sélectionner précisément les aperçus à générer ou à mettre à jour.
- Prévisualisez les variantes. La boîte de dialogue liste individuellement toutes les variantes d'aperçu (comme le thème clair ou le thème sombre, ou différents appareils), ce qui vous permet de sélectionner ou de désélectionner des éléments spécifiques avant de générer des images.

Résultats de test et outil de comparaison intégrés : Affichez les résultats sans quitter l'IDE.
- Panneau d'exécution unifié : Les résultats des tests de capture d'écran s'affichent dans la fenêtre d'outil Exécuter standard. Les tests sont regroupés par classe et par fonction, avec un état de réussite ou d'échec clairement indiqué.
- Outil de comparaison visuelle Lorsqu'un test échoue, l'onglet Capture d'écran vous permet de comparer les images Référence, Réel et Différence côte à côte.
- Attributs détaillés : Un onglet Attributs fournit des métadonnées sur les tests ayant échoué, y compris le pourcentage de correspondance, les dimensions de l'image et la configuration d'aperçu spécifique utilisée (par exemple, uiMode ou fontScale).

Définition flexible du champ d'application des tests : Vous pouvez désormais exécuter des tests de capture d'écran avec différentes portées directement depuis la vue du projet. Effectuez un clic droit sur un module, un répertoire, un fichier ou une classe pour exécuter des tests de capture d'écran spécifiquement pour cette sélection.

Conditions requises

Pour utiliser les tests de capture d'écran Compose Preview via l'intégration complète de l'IDE, votre projet doit répondre aux exigences suivantes :

Android Studio Panda 1 Canary 4 ou version ultérieure.
Plug-in Android Gradle (AGP) version 9.0 ou ultérieure.
Plug-in Compose Preview Screenshot Testing version 0.0.1-alpha14 ou ultérieure.
Kotlin version 2.2.10 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.

Si vous souhaitez uniquement utiliser les tâches Gradle sous-jacentes sans l'intégration de l'IDE, les exigences sont les suivantes :

Plug-in Android Gradle (AGP) version 8.5.0 ou ultérieure.
Plug-in Compose Preview Screenshot Testing version 0.0.1-alpha14 ou ultérieure.
Kotlin version 1.9.20 ou 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 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

L'outil intégré et les tâches Gradle sous-jacentes s'appuient sur le plug-in Compose Preview Screenshot Testing. Pour configurer le plug-in, procédez comme suit :

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 le plug-in com.android.compose.screenshot, version 0.0.1-alpha14, à votre projet.
1. Ajoutez le plug-in à votre fichier de catalogues de versions :
```
[versions]
agp = "9.0.0-rc03"
kotlin = "2.1.20"
screenshot = "0.0.1-alpha14"

[plugins]
screenshot = { id = "com.android.compose.screenshot", version.ref = "screenshot"}
```
2. Dans le fichier build.gradle.kts au niveau du module, ajoutez le plug-in dans le bloc plugins {} :
```
plugins {
    alias(libs.plugins.screenshot)
}
```

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 aperçus 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 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 les tests de capture d'écran de prévisualisation de votre composable, suivez les instructions de cette section pour l'intégration de l'IDE ou pour les tâches Gradle.

Dans l'IDE

Cliquez sur l'icône en forme de gouttière à côté d'une fonction @PreviewTest, puis sélectionnez Add/Update Reference Images (Ajouter/Mettre à jour les images de référence). Sélectionnez les aperçus dans la boîte de dialogue, puis cliquez sur Ajouter.

Avec les tâches Gradle

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 disponibles, générez un rapport de test en suivant les instructions de cette section pour l'intégration de l'IDE ou pour les tâches Gradle.

Dans l'IDE

Cliquez sur l'icône en forme de gouttière à côté d'une fonction @PreviewTest, puis sélectionnez Run 'ScreenshotTests' (Exécuter 'ScreenshotTests').

Si un test échoue, cliquez sur son nom dans le panneau Exécuter. Sélectionnez l'onglet Capture d'écran pour inspecter la différence d'image à l'aide des commandes de zoom et de déplacement intégrées.

Avec les tâches Gradle

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

Kotlin Multiplatform (KMP) : l'IDE et le plug-in sous-jacent sont conçus exclusivement pour les projets Android. Ils ne sont pas compatibles avec les cibles non Android dans les projets KMP.

Vous trouverez la liste complète des problèmes connus actuels 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

Pour obtenir la liste complète des mises à jour, consultez les notes de version.

Test de capture d'écran de l'aperçu Compose Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.

Intégration de l'IDE

Conditions requises

Configuration

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

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

Dans l'IDE

Avec les tâches Gradle

Générer un rapport de test

Dans l'IDE

Avec les tâches Gradle

Problèmes connus

Mises à jour des versions

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