Test zum Erstellen eines Screenshots mit der Vorschau

Screenshot-Tests sind eine effektive Methode, um zu prüfen, wie Ihre Benutzeroberfläche für Nutzer aussieht. Das Compose Preview Screenshot Testing-Tool kombiniert die Einfachheit und die Funktionen von komponierbaren Vorschauen mit den Produktivitätsvorteilen von hostseitigen Screenshot-Tests. Compose Preview Screenshot Testing ist so einfach zu verwenden wie composable Vorschauen.

android skills add testing-setup

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 können Sie:

• Mit @PreviewTest können Sie Screenshot-Tests für vorhandene oder neue Composable-Vorschauen erstellen.
• Referenzbilder aus diesen composable Vorschauen generieren.
• Generieren Sie einen HTML-Bericht, in dem Änderungen an diesen Vorabversionen nach Codeänderungen aufgeführt sind.
• Verwenden Sie @Preview-Parameter wie uiMode oder fontScale und Multi-Previews, um Ihre Tests zu skalieren.
• Modularisieren Sie Ihre Tests mit dem neuen Source-Set screenshotTest.

IDE-Einbindung

Sie können das Tool für Screenshot-Tests für die Compose-Vorschau verwenden, indem Sie die zugrunde liegenden Gradle-Aufgaben (updateScreenshotTest und validateScreenshotTest) manuell ausführen. Mit dem Feature Drop für Android Studio Otter 3 Canary 4 wird jedoch 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:

• Symbole im Editor-Gutter. Sie können jetzt Tests ausführen oder Referenzbilder direkt aus dem Quellcode aktualisieren. Im Gutter neben den mit @PreviewTest annotierten Composables und Klassen werden grüne Ausführungssymbole angezeigt.
  • Screenshot-Tests ausführen Tests speziell für eine einzelne Funktion oder für eine ganze Klasse ausführen.
  • Referenzbilder hinzufügen oder aktualisieren Lösen Sie den Update-Vorgang speziell für den ausgewählten Bereich aus.

• Interaktive Referenzverwaltung Das Aktualisieren von Referenzbildern ist jetzt sicherer und detaillierter.
  • Neues Dialogfeld zum Generieren von Referenzbildern. Anstatt einen Bulk-Gradle-Task auszuführen, können Sie in einem neuen Dialogfeld genau sehen und 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. Sie können bestimmte Elemente auswählen oder die Auswahl aufheben, bevor Sie Bilder generieren.

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

• Flexible Testbereiche: Sie können jetzt Screenshot-Tests mit verschiedenen Bereichen direkt in der Projektansicht ausführen. Rechtsklicken Sie 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.
• Compose Preview Screenshot Testing-Plug-in, Version 0.0.1-alpha16 oder höher.
• 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.
• Compose Preview Screenshot Testing-Plug-in, Version 0.0.1-alpha16 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 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 Plug-in für Screenshot-Tests in der Compose-Vorschau. Führen Sie folgende Schritte zur Einrichtung des Plug-ins aus:

1. Aktivieren Sie das experimentelle Attribut in der gradle.properties-Datei Ihres Projekts.

   android.experimental.enableScreenshotTest=true
   

2. Aktivieren Sie im android {}-Block der 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 Plug-in com.android.compose.screenshot, Version 0.0.1-alpha16, hinzu.

   1. Fügen Sie das Plug-in Ihrer Versionskatalogdatei 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 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 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)
      }
      

Festlegen, welche composable Vorschauen für Screenshot-Tests verwendet werden sollen

Wenn Sie die composable Vorschauen festlegen möchten, die Sie für Screenshot-Tests verwenden möchten, markieren Sie die Vorschauen mit der Annotation @PreviewTest. Die Vorabversionen müssen sich im neuen screenshotTest-Source-Set befinden, zum Beispiel:

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

Sie können dieser Datei oder anderen Dateien, die im selben Source-Set 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 Änderungen zu identifizieren, nachdem Sie Codeänderungen vorgenommen haben. Wenn Sie Referenzbilder für Ihre Screenshot-Tests für die composable Vorschau generieren möchten, folgen Sie der Anleitung in diesem Abschnitt für die IDE-Integration oder für die Gradle-Aufgaben.

android studio render-compose-preview

In der IDE

Klicken Sie auf das Gutter-Symbol neben einer @PreviewTest-Funktion 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)

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

Testbericht erstellen

Sobald 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 auf das Symbol im Zwischenraum neben einer @PreviewTest-Funktion 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 prüfen.

Mit den Gradle-Aufgaben

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

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

Die Überprüfungsaufgabe erstellt einen HTML-Bericht unter {module}/build/reports/screenshotTest/preview/{variant}/index.html.

Fehlerbehebung

Beim Compose Preview Screenshot Testing werden hostseitige 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 der Datei gradle.properties das folgende Attribut hinzufü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 aktuell bekannten Probleme finden Sie in der Issue Tracker-Komponente des Tools. Sonstiges Feedback und Probleme können Sie über den Issue Tracker melden.

Versionsupdates

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