Screenshot-Tests mit Test-Suites

Ab Android-Gradle-Plug-in (AGP) 9.5.0-alpha03 und Compose Preview-Screenshot-Test-Engine 0.0.1-alpha16 sind Screenshot-Tests in das native Test-Suites-Framework von AGP integriert.

Dieser Ansatz ersetzt das eigenständige Screenshot-Plug-in (com.android.compose.screenshot). Wir empfehlen, AGP-Testsuiten aus den folgenden Gründen zu verwenden:

  • Nativer Gradle-Aufgabenlebenszyklus: Screenshot-Tests werden direkt in die standardmäßigen Gradle- und AGP-Testlebenszyklen eingebunden. Dadurch wird die Aufgabenisolation verbessert und die Zuverlässigkeit der Testausführung erhöht.
  • Unterstützung von mehreren Varianten und benutzerdefinierten Testsuites: Sie können mehrere unterschiedliche Screenshot-Testsuites (z. B. screenshotTest, uiTests oder smokeTests) in einem einzelnen Modul erstellen und auf bestimmte Build-Varianten (z. B. demoDebug oder release) ausrichten, anstatt auf einen einzelnen vorkonfigurierten Quellsatz beschränkt zu sein.
  • Verbesserte Build-Leistung und ‑Isolation: AGP-Testsuiten verwenden integrierte Artefakttransformationen (z. B. Layoutlib-Laufzeit-Extraktion) und isoliertes Classloading mit voller Unterstützung für Gradle-Konfigurations-Caching und Projektisolation.

Voraussetzungen

Wenn Sie Compose Screenshot Testing mit Test-Suites verwenden möchten, muss Ihre Umgebung die folgenden Anforderungen erfüllen:

  • Android Studio Rabbit 1 Canary 4 oder höher.
  • Android-Gradle-Plug-in (AGP) Version 9.5.0-alpha03 oder höher.
  • Compose Screenshot Engine-Version 0.0.1-alpha16 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.

Einrichtung und Konfiguration

Führen Sie die folgenden Schritte aus, um Compose-Screenshot-Tests mit Test-Suites zu konfigurieren:

1. Experimentelle Flags aktivieren

Aktivieren Sie in der gradle.properties-Datei des Stammverzeichnisses Ihres Projekts Screenshot-Tests und die Unterstützung von Testsuites:

android.experimental.enableScreenshotTest=true
android.experimental.testSuiteSupport=true

2. Test-Suite in der Datei build.gradle.kts konfigurieren

Definieren Sie in der build.gradle.kts-Datei Ihres Moduls eine Screenshot-Testsuite im testOptions-Block:

android {
    testOptions {
        screenshotTests.create("screenshotTest") { // suiteName can be customized (for example, "uiTests")
            engineVersion = "0.0.1-alpha16"
            targetVariants.add("demoDebug") // Add specific variants to test

            dependencies {
                implementation(libs.androidx.compose.ui.tooling)
                implementation("com.android.tools.screenshot:screenshot-validation-api:0.0.1-alpha16")
            }
        }
    }
}

3. Source-Set erstellen

Erstellen Sie ein dediziertes Source-Set-Verzeichnis, das mit dem Namen Ihrer Suite übereinstimmt:

{module}/src/{suiteName}/kotlin/

Beispiel für eine Suite mit dem Namen screenshotTest:

feature/foryou/impl/src/screenshotTest/kotlin/com/example/app/ForYouScreenTest.kt

4. Composable-Vorschaubilder definieren

Composables mit @PreviewTest und Standard-@Preview- oder Multi-Preview-Annotationen versehen:

package com.example.app

import androidx.compose.runtime.Composable
import androidx.compose.ui.tooling.preview.Preview
import com.android.tools.screenshot.PreviewTest
import com.example.app.ui.theme.AppTheme

@PreviewTest
@Preview(showBackground = true)
@Composable
fun ForYouScreenPreview() {
    AppTheme {
        ForYouScreen(isSyncing = false)
    }
}

Screenshot-Tests ausführen

AGP-Testsuites generieren basierend auf dem Namen der Suite, dem Ziel und den Varianten dedizierte Gradle-Aufgaben.

1. Referenzbilder generieren oder aktualisieren

Composable-Vorschauen rendern und die Golden Baseline-Referenzbilder speichern:

  • Linux und macOS: ./gradlew update{SuiteName}{Target}{Variant}TestSuite (z. B. ./gradlew updateScreenshotTestDefaultDemoDebugTestSuite)
  • Windows: gradlew updateScreenshotTestDefaultDemoDebugTestSuite

Referenzbilder werden generiert und unter folgendem Pfad gespeichert:

{module}/src/{suiteName}{Target}{Variant}/reference/

2. Tests überprüfen und ausführen

Neue Screenshots rendern und mit Referenzbildern vergleichen:

  • Linux und macOS: ./gradlew test{SuiteName}{Target}{Variant}TestSuite (z. B. ./gradlew testScreenshotTestDefaultDemoDebugTestSuite)
  • Windows: gradlew testScreenshotTestDefaultDemoDebugTestSuite

Testberichte prüfen

Wenn Unterschiede erkannt oder Tests nicht bestanden werden, generiert AGP einen HTML-Testbericht.

  • Berichtspfad: {module}/build/reports/tests/{taskName}/index.html (z. B. app/build/reports/tests/testScreenshotTestDefaultDemoDebugTestSuite/index.html)

Der aktualisierte Bericht enthält:

  • Infokarte mit Kopfzeilenmetadaten: Hier werden der Testname, die Vorschau-Methode, die Variante, die Suite und das Statussymbol angezeigt.
  • Fehlerkategorisierung: Reference Image Missing, Image Size Mismatch oder Pixel Mismatch werden deutlich mit kopierbaren Stacktraces gekennzeichnet.
  • Dynamischer visueller Unterschied: Hier werden subtile Änderungen mit geringerer Intensität und größere Änderungen mit hohem Kontrast hervorgehoben, um zu verhindern, dass verschachtelte Elemente verschwinden.

Vom alten eigenständigen Plug-in migrieren

Wenn Sie vom alten eigenständigen Screenshot-Plug-in zu AGP-Testsuiten migrieren möchten, müssen Sie Ihre Gradle-Konfiguration und Aufgabenbefehle aktualisieren.

Vergleich der DSL für die Build-Konfiguration

Eigenständiges Legacy-Plug-in (eingestellt)

// In build.gradle.kts
plugins {
    alias(libs.plugins.screenshot)
}

dependencies {
    screenshotTestImplementation(libs.androidx.compose.ui.tooling)
    screenshotTestImplementation("com.android.tools.screenshot:screenshot-validation-api:0.0.1-alpha16")
}

// In build.gradle.kts
android {
    testOptions {
        screenshotTests.create("screenshotTest") {
            engineVersion = "0.0.1-alpha16"
            targetVariants.add("demoDebug")

            dependencies {
                implementation(libs.androidx.compose.ui.tooling)
                implementation("com.android.tools.screenshot:screenshot-validation-api:0.0.1-alpha16")
            }
        }
    }
}

Zuordnung von Aufgaben und Pfaden

Vorgabe Legacy-Einrichtung (eingestellt) AGP-Test-Suites (empfohlen)
Aufgabe aktualisieren ./gradlew updateDebugScreenshotTest ./gradlew update{SuiteName}{Target}{Variant}TestSuite
Testaufgabe ./gradlew validateDebugScreenshotTest ./gradlew test{SuiteName}{Target}{Variant}TestSuite
Referenzpfad src/screenshotTestDebug/reference src/{suiteName}{Target}{Variant}/reference
Berichtspfad build/reports/screenshotTest/debug/ build/reports/tests/{taskName}/