Test zum Erstellen eines Screenshots mit der Vorschau

Mit Screenshot-Tests lässt sich effektiv überprüfen, wie Ihre Benutzeroberfläche für Nutzer aussieht. Das Compose Preview Screenshot Testing-Tool kombiniert die Einfachheit und die Funktionen von Composable-Vorschauen mit den Produktivitätsvorteilen von Screenshot-Tests auf Hostseite. Compose Preview Screenshot Testing ist so einfach zu verwenden wie zusammensetzbare Vorschauen.

Ein Screenshot-Test ist ein automatisierter Test, bei dem ein Screenshot eines Teils der Benutzeroberfläche 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 Compose Preview Screenshot Testing-Tool haben Sie folgende Möglichkeiten:

  • Mit @PreviewTest können Sie Screenshot-Tests für vorhandene oder neue zusammensetzbare Vorschauen erstellen.
  • Referenzbilder aus diesen zusammensetzbaren Vorschauen generieren
  • Erstellen Sie einen HTML-Bericht, in dem Änderungen an diesen Vorschauen nach der Vornahme von Codeänderungen aufgeführt werden.
  • Verwenden Sie @Preview-Parameter wie uiMode oder fontScale und mehrere Vorschauen, um Ihre Tests zu skalieren.
  • Mit dem neuen screenshotTest Source-Set können Sie Ihre Tests modularisieren.
Abbildung 1. Beispiel für einen HTML-Bericht.

IDE-Einbindung

Sie können das Tool „Compose Preview Screenshot Testing“ zwar verwenden, indem Sie die zugrunde liegenden Gradle-Aufgaben (updateScreenshotTest und validateScreenshotTest) manuell ausführen, aber mit Android Studio Otter 3 Feature Drop Canary 4 wird eine vollständige IDE-Integration eingeführt. So können Sie Referenzbilder generieren, Tests ausführen und Validierungsfehler direkt in der IDE analysieren. Hier sind einige der wichtigsten Funktionen:

  • Rinnensymbole im Editor: Sie können jetzt Tests ausführen oder Referenzbilder direkt über den Quellcode aktualisieren. Grüne Ausführungssymbole werden in der Spalte neben Composables 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 Quellenverwaltung: Das Aktualisieren von Referenzbildern ist jetzt sicherer und detaillierter.
    • Neues Dialogfeld zum Generieren von Referenzbildern: Anstatt einen Gradle-Bulk-Task auszuführen, können Sie in einem neuen Dialogfeld genau auswählen, welche Vorschauen generiert oder aktualisiert werden sollen.
    • Vorschau von Varianten ansehen: 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 abwählen, bevor Sie Bilder generieren.

  • Integrierte Testergebnisse und Diff-Viewer. Ergebnisse ansehen, ohne die IDE zu verlassen
    • Einheitlicher Laufbereich: Die Ergebnisse von Screenshot-Tests werden im Standard-Toolfenster Run angezeigt. Tests sind nach Klasse und Funktion gruppiert und der Status „Bestanden“ oder „Nicht bestanden“ ist deutlich gekennzeichnet.
    • Tool zum visuellen Vergleich: Wenn ein Test fehlschlägt, können Sie auf dem Tab Screenshot die Bilder Referenz, Tatsächlich und Differenz nebeneinander vergleichen.
    • Detaillierte Attribute: Auf dem Tab Attribute finden Sie Metadaten zu fehlgeschlagenen Tests, einschließlich des Übereinstimmungsprozentsatzes, der Bildabmessungen und der verwendeten Vorschaukonfiguration (z. B. uiMode oder fontScale).

  • Flexibler Testumfang: Sie können jetzt Screenshot-Tests mit verschiedenen Bereichen direkt über die 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 Compose Preview Screenshot Testing über die vollständige IDE-Integration 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.
  • Version 0.0.1-alpha16 oder höher des Compose Preview Screenshot Testing-Plug-ins.
  • Kotlin-Version 2.2.10 oder höher.
  • JDK-Version 17 oder höher.
  • Compose ist für Ihr Projekt aktiviert. Wir empfehlen, Compose mit dem Compose Compiler Gradle-Plug-in zu aktivieren.

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

  • Android-Gradle-Plug-in (AGP) Version 8.5.0 oder höher.
  • Version 0.0.1-alpha16 oder höher des Compose Preview Screenshot Testing-Plug-ins.
  • Kotlin-Version 1.9.20 oder höher. Wir empfehlen die Verwendung von Kotlin 2.0 oder höher, damit Sie das Compose Compiler Gradle-Plug-in verwenden können.
  • JDK-Version 17 oder höher.
  • Compose ist für Ihr Projekt aktiviert. Wir empfehlen, Compose mit dem Compose Compiler Gradle-Plug-in zu aktivieren.

Einrichtung

Sowohl das integrierte Tool als auch die zugrunde liegenden Gradle-Aufgaben basieren auf dem Compose Preview Screenshot Testing-Plug-in. Führen Sie folgende Schritte zur Einrichtung des Plug-ins aus:

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

    android.experimental.enableScreenshotTest=true

  2. Aktivieren Sie im Block android {} Ihrer build.gradle.kts-Datei auf Modulebene das experimentelle Flag, um das Source-Set screenshotTest zu verwenden.

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

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

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

      [versions]
agp = "9.0.0-rc03"
kotlin = "2.2.10"
screenshot = "0.0.1-alpha16"

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

    2. Fügen Sie in der Datei build.gradle.kts auf Modulebene das Plug-in im Block plugins {} hinzu:

      plugins {
    alias(libs.plugins.screenshot)
}

  4. Fügen Sie die Abhängigkeiten screenshot-validation-api und ui-tooling 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)
}

Composable-Vorschauen für Screenshot-Tests festlegen

Wenn Sie die Composable-Vorschauen angeben möchten, die für Screenshot-Tests verwendet werden sollen, markieren Sie die Vorschauen mit der Annotation @PreviewTest. Die Vorschauen müssen sich im neuen Quellset screenshotTest befinden, z. B.:

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

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

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 für jede Vorschau Referenzbilder generieren. Diese Referenzbilder werden verwendet, um später nach Codeänderungen Änderungen zu erkennen. Wenn Sie Referenzbilder für Ihre Screenshots von Komposable-Vorschaubildern erstellen möchten, folgen Sie der Anleitung in diesem Abschnitt für die IDE-Integration oder für die Gradle-Aufgaben.

In der IDE

Klicken Sie neben einer @PreviewTest-Funktion auf das Rinnensymbol und wählen Sie Referenzbilder hinzufügen/aktualisieren aus. Wählen Sie die Vorschauen im Dialogfeld 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)

Nachdem die Aufgabe abgeschlossen ist, finden Sie die Referenzbilder unter app/src/screenshotTestDebug/reference ({module}/src/screenshotTest{Variant}/reference).

Testbericht erstellen

Nachdem Referenzbilder vorhanden sind, können Sie einen Testbericht erstellen. Folgen Sie dazu der Anleitung in diesem Abschnitt für die IDE-Integration oder für die Gradle-Aufgaben.

In der IDE

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

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

Mit den Gradle-Aufgaben

Führen Sie die Aufgabe „validate“ 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)

Der Schritt im Überprüfungsverfahren erstellt einen HTML-Bericht unter {module}/build/reports/screenshotTest/preview/{variant}/index.html.

Fehlerbehebung

Beim Compose Preview Screenshot Testing werden Host-seitige Tests ausgeführt, die speicherintensiv sein können. Sie können die maximale Heap-Größe für die Test-JVM erhöhen, indem Sie die folgende Eigenschaft in Ihre gradle.properties-Datei einfügen:

android.compose.screenshot.maxHeapSize=4g

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.

Eine vollständige Liste der aktuellen bekannten Probleme finden Sie in der Fehlerbehebungskomponente des Tools. Anderes Feedback und andere Probleme können Sie über den Issue Tracker melden.

Versionsupdates

Eine vollständige Liste der Release-Updates finden Sie in den Versionshinweisen.