Test zum Erstellen eines Screenshots mit der Vorschau

Mit Screenshot-Tests lässt sich effektiv überprüfen, wie die 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
  • Generieren 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 Quellsatz screenshotTest können Sie Ihre Tests modularisieren.
Abbildung 1. Beispiel für einen HTML-Bericht.

Voraussetzungen

Für Compose Preview Screenshot Testing benötigen Sie Folgendes:

  • Android-Gradle-Plug-in 8.5.0 oder höher.
  • Kotlin 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 23 oder niedriger.

  • Compose ist für Ihr Projekt aktiviert. Wir empfehlen, Compose mit dem Compose Compiler Gradle-Plug-in zu aktivieren.

Einrichten

So aktivieren Sie das Tool:

  1. Aktivieren Sie die experimentelle Eigenschaft in der gradle.properties-Datei Ihres Projekts. 
          android.experimental.enableScreenshotTest=true
  2. Aktivieren Sie im Block android {} der Datei build.gradle.kts auf Modulebene das experimentelle Flag, um die Quelle 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-alpha11 hinzu.
    1. Fügen Sie das Plug-in Ihrer Versionskatalogdatei hinzu: 
                [versions]
          agp = "8.11.0-alpha06"
          kotlin = "2.1.20"
          screenshot = "0.0.1-alpha11"

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

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 Vorschaubilder 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 Quellset erstellt wurden, weitere Composables und/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 für jede Vorschau Referenzbilder generieren. Diese Referenzbilder werden verwendet, um später Änderungen zu erkennen, nachdem Sie Codeänderungen vorgenommen haben. Führen Sie die folgende Gradle-Aufgabe aus, um Referenzbilder für die Screenshot-Tests für zusammensetzbare Vorschau zu generieren:

  • 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, 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)

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

Bekannte Probleme

Die aktuelle Liste bekannter Probleme finden Sie in der Problemverfolgungskomponente des Tools. Anderes Feedback und Probleme können Sie über den Issue Tracker melden.

Versionsupdates

0.0.1-alpha11

In dieser Version wird Folgendes eingeführt:

  • Kompatibilität mit dem Android-Gradle-Plug-in (AGP) 8.13.
  • Unterstützung für das Parsen von XML-Drawables mit Dezimalwerten unabhängig vom Gebietsschema des Hostcomputers hinzugefügt.
  • Für einen Hostcomputer mit JDK 24 oder höher wird ein kompatibles JDK (11–23) ausgewählt, sofern eines installiert ist.

0.0.1-alpha10

In dieser Version wird Folgendes eingeführt:

  • Ab dieser Version müssen Sie alle Preview-Funktionen mit der Annotation @PreviewTest kennzeichnen. Vorschauen ohne die Anmerkung werden nicht ausgeführt.

  • Das Verzeichnis für Referenzbilder wurde von {module}/src/{variant}/screenshotTest/reference in {module}/src/screenshotTest{Variant}/reference geändert. So wird sichergestellt, dass die generierten Referenzbilder nicht Teil des Produktionscodes sind, und die Verzeichnisstruktur anderer Testtypen wird eingehalten.

  • Die Aufgabe {variant}PreviewScreenshotRender wird entfernt. Das Bildrendering wird in die JUnit Test Engine migriert.

  • Bei der Aufgabe update{Variant}ScreenshotTest werden neue Rendering-Bilder mit Referenzbildern verglichen, bevor sie aktualisiert werden. Es werden nur Bilder aktualisiert, die Unterschiede aufweisen, die einen bestimmten Schwellenwert überschreiten. Der --updateFilter-Befehlszeilenparameter wurde entfernt.

0.0.1-alpha06

In dieser Version wird Folgendes eingeführt:

Schwellenwert für Bildunterschiede: Mit dieser neuen globalen Schwellenwerteinstellung können Sie Screenshot-Vergleiche genauer steuern. So konfigurieren Sie die build.gradle.kts-Datei Ihres Moduls:

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

Dieser Grenzwert wird auf alle im Modul definierten Screenshot-Tests angewendet.

  • Fehlerkorrekturen: Einige Fehler im Compose-Renderer wurden behoben und es wurde Unterstützung für leere Compose-Elemente hinzugefügt.
  • Leistungsverbesserungen: Der Algorithmus für den Bildvergleich wurde aktualisiert, um schneller zu sein.