Test zum Erstellen eines Screenshots mit der Vorschau

Screenshot-Tests sind eine effektive Möglichkeit, um zu prüfen, wie Ihre UI für Nutzer aussieht. Das Tool „Screenshot-Tests für Compose-Vorschauen“ kombiniert die Einfachheit und die Funktionen von zusammensetzbaren Vorschauen mit den Produktivitäts vorteilen von Screenshot-Tests auf Hostseite. Die Screenshot-Tests für Compose-Vorschauen sind so konzipiert, dass sie genauso einfach zu verwenden sind wie zusammensetzbare Vorschauen.

Ein Screenshot-Test ist ein automatisierter Test, bei dem ein Screenshot eines UI-Elements erstellt und dann mit einem zuvor genehmigten Referenzbild verglichen wird. Wenn die Bilder nicht übereinstimmen, schlägt der Test fehl und es wird ein HTML-Bericht erstellt, mit dem Sie die Unterschiede vergleichen und finden können.

Mit dem Tool „Screenshot-Tests für Compose-Vorschauen“ haben Sie folgende Möglichkeiten:

  • Mit @PreviewTest Screenshot-Tests für vorhandene oder neue zusammensetzbare Vorschauen erstellen.
  • Referenzbilder aus diesen zusammensetzbaren Vorschauen generieren.
  • Einen HTML-Bericht erstellen, in dem Änderungen an diesen Vorschauen nach Codeänderungen aufgeführt sind.
  • @Preview-Parameter wie uiMode oder fontScale und Multi-Vorschauen verwenden, um Ihre Tests zu skalieren.
  • Ihre Tests mit dem neuen Quellsatz screenshotTest modularisieren.
Abbildung 1. Beispiel für einen HTML-Bericht.

IDE-Einbindung

Sie können das Tool „Screenshot-Tests für Compose-Vorschauen“ verwenden, indem Sie die zugrunde liegenden Gradle-Aufgaben (updateScreenshotTest und validateScreenshotTest) manuell ausführen. Android Studio Otter 3 Feature Drop Canary 4 bietet jedoch eine vollständige IDE-Einbindung. So können Sie Referenzbilder generieren, Tests ausführen und Validierungsfehler direkt in der IDE analysieren. Hier sind einige der wichtigsten Funktionen:

  • Gutter-Symbole im Editor Sie können jetzt Tests ausführen oder Referenzbilder direkt aus dem Quellcode aktualisieren. Grüne Ausführungssymbole werden im Gutter neben zusammensetzbaren Elementen und Klassen angezeigt, die mit @PreviewTest annotiert sind.
    • Screenshot-Tests ausführen Führen Sie Tests speziell für eine einzelne Funktion oder für eine ganze Klasse aus.
    • Referenzbilder hinzufügen oder aktualisieren Lösen Sie den Aktualisierungsvorgang speziell für den ausgewählten Bereich aus.

  • Interaktive Referenzverwaltung Das Aktualisieren von Referenzbildern ist jetzt sicherer und detaillierter.
    • Neues Dialogfeld zur Generierung von Referenzbildern Anstatt eine Gradle-Bulk-Aufgabe auszuführen, können Sie in einem neuen Dialogfeld genau visualisieren und auswählen, welche Vorschauen generiert oder aktualisiert werden sollen.
    • Vorschau von Varianten Im Dialogfeld werden alle Vorschauvarianten (z. B. helles oder dunkles Design oder verschiedene Geräte) einzeln aufgeführt. So können Sie bestimmte Elemente auswählen oder die Auswahl aufheben, bevor Sie Bilder generieren.

  • Integrierte Testergebnisse und Diff-Viewer Sie können die Ergebnisse ansehen, ohne die IDE zu verlassen.
    • Einheitliches Ausführungsfenster Die Ergebnisse von Screenshot-Tests werden im Standardtoolfenster Ausführen angezeigt. Tests werden nach Klasse und Funktion gruppiert, wobei der Status „Bestanden“ oder „Fehlgeschlagen“ deutlich gekennzeichnet ist.
    • Visuelles Diff-Tool Wenn ein Test fehlschlägt, können Sie auf dem Tab Screenshot die Bilder Referenz, Aktuell und Unterschied nebeneinander vergleichen.
    • Detaillierte Attribute Auf dem Tab Attribute finden Sie Metadaten zu fehlgeschlagenen Tests, einschließlich des Übereinstimmungsprozentsatzes, der Bildabmessungen und der verwendeten spezifischen Vorschaukonfiguration (z. B. uiMode oder fontScale).

  • Flexible Testbereiche Sie können jetzt Screenshot-Tests mit verschiedenen Bereichen direkt in der Projektansicht ausführen. Klicken Sie mit der rechten Maustaste auf ein Modul, ein Verzeichnis, eine Datei oder eine Klasse, um Screenshot-Tests speziell für diese Auswahl auszuführen.

Voraussetzungen

Wenn Sie Screenshot-Tests für Compose-Vorschauen über die vollständige IDE-Einbindung verwenden möchten, muss Ihr Projekt die folgenden Anforderungen erfüllen:

  • Android Studio Panda 1 Canary 4 oder höher
  • Android Gradle-Plug-in (AGP) Version 9.0 oder höher
  • Plug-in „Screenshot-Tests für Compose-Vorschauen“ Version 0.0.1-alpha14 oder höher
  • Kotlin Version 2.2.10 oder höher
  • JDK Version 17 oder höher
  • Compose für Ihr Projekt aktiviert Wir empfehlen, Compose mit dem Gradle-Plug-in für den Compose-Compiler zu aktivieren.

Wenn Sie nur die zugrunde liegenden Gradle-Aufgaben ohne die IDE-Einbindung verwenden möchten, gelten die folgenden Anforderungen:

  • Android Gradle-Plug-in (AGP) Version 8.5.0 oder höher
  • Plug-in „Screenshot-Tests für Compose-Vorschauen“ Version 0.0.1-alpha14 oder höher
  • Kotlin Version 1.9.20 oder höher Wir empfehlen die Verwendung von Kotlin 2.0 oder höher, damit Sie das Gradle-Plug-in für den Compose-Compiler verwenden können.
  • JDK Version 17 oder höher
  • Compose für Ihr Projekt aktiviert Wir empfehlen, Compose mit dem Gradle-Plug-in für den Compose-Compiler zu aktivieren.

Einrichtung

Sowohl das integrierte Tool als auch die zugrunde liegenden Gradle-Aufgaben basieren auf dem Plug-in „Screenshot-Tests für Compose-Vorschauen“. So richten Sie das Plug-in ein:

  1. Aktivieren Sie die experimentelle Eigenschaft in der Datei gradle.properties Ihres Projekts.

    android.experimental.enableScreenshotTest=true

  2. Aktivieren Sie im Block android {} der Datei build.gradle.kts auf Modulebene das experimentelle Flag, um den Quellsatz screenshotTest zu verwenden.

    android {
    experimentalProperties["android.experimental.enableScreenshotTest"] = true
}

  3. Fügen Sie Ihrem Projekt das Plug-in com.android.compose.screenshot in Version 0.0.1-alpha14 hinzu.

    1. Fügen Sie das Plug-in der Datei mit den Versionskatalogen hinzu:

      [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. Fügen Sie das Plug-in in der Datei build.gradle.kts auf Modulebene im Block plugins {} hinzu:

      plugins {
    alias(libs.plugins.screenshot)
}

  4. Fügen Sie die screenshot-validation-api und ui-tooling Abhängigkeiten hinzu.

    1. Fügen Sie sie Ihren Versionskatalogen hinzu:

      [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"}

    2. Fügen Sie sie der Datei build.gradle.kts auf Modulebene hinzu:

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

Zusammensetzbare Vorschauen für Screenshot-Tests festlegen

Wenn Sie die zusammensetzbaren Vorschauen festlegen möchten, die Sie für Screenshot-Tests verwenden möchten, markieren Sie die Vorschauen mit der Annotation @PreviewTest. Die Vorschauen müssen sich im neuen Quellsatz screenshotTest befinden, z. B.:

app/src/screenshotTest/kotlin/com/example/yourapp/ ExamplePreviewScreenshotTest.kt

Sie können dieser Datei oder anderen Dateien, die im selben Quellsatz erstellt wurden, weitere zusammensetzbare Elemente oder Vorschauen hinzufügen, einschließlich Multi-Vorschauen.

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!")
    }
}

Referenzbilder generieren

Nachdem Sie eine Testklasse eingerichtet haben, müssen Sie Referenzbilder für jede Vorschau generieren. Diese Referenzbilder werden später verwendet, um Änderungen zu erkennen, nachdem Sie Codeänderungen vorgenommen haben. Wenn Sie Referenzbilder für Ihre Screenshot-Tests für zusammensetzbare Vorschauen generieren möchten, folgen Sie der Anleitung in diesem Abschnitt für die IDE-Einbindung oder für die Gradle-Aufgaben.

In der IDE

Klicken Sie neben einer @PreviewTest-Funktion auf das Gutter-Symbol und wählen Sie Referenzbilder hinzufügen/aktualisieren aus. Wählen Sie im Dialogfeld die Vorschauen aus und klicken Sie auf Hinzufügen.

Mit den Gradle-Aufgaben

Führen Sie die folgende Gradle-Aufgabe aus:

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

Nach Abschluss der Aufgabe finden Sie die Referenzbilder unter app/src/screenshotTestDebug/reference ({module}/src/screenshotTest{Variant}/reference).

Testbericht erstellen

Sobald die Referenzbilder vorhanden sind, erstellen Sie einen Testbericht. Folgen Sie dazu der Anleitung in diesem Abschnitt für die IDE-Einbindung oder für die Gradle-Aufgaben.

In der IDE

Klicken Sie neben einer @PreviewTest-Funktion auf das Gutter-Symbol und wählen Sie „ScreenshotTests“ ausführen aus.

Wenn ein Test fehlschlägt, klicken Sie im Fenster Ausführen auf den Testnamen. Wählen Sie den Tab Screenshot aus, um den Bildunterschied mit den integrierten Zoom- und Schwenksteuerungen zu untersuchen.

Mit den Gradle-Aufgaben

Führen Sie die Validierungsaufgabe aus, um einen neuen Screenshot zu erstellen und ihn mit dem Referenzbild zu vergleichen:

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

Bei der Validierungsaufgabe wird ein HTML-Bericht unter {module}/build/reports/screenshotTest/preview/{variant}/index.html erstellt.

Bekannte Probleme

  • Kotlin Multiplatform (KMP) : Sowohl die IDE als auch das zugrunde liegende Plug-in sind ausschließlich für Android-Projekte konzipiert. Sie unterstützen keine Nicht-Android-Ziele in KMP-Projekten.

Die vollständige Liste der aktuellen bekannten Probleme finden Sie in der Problemverfolgung des Tools . Feedback und Probleme können über die Problemverfolgung gemeldet werden.

Versionsupdates

Eine vollständige Liste der Versionsupdates finden Sie in den Versionshinweisen.