Testowanie zrzutów ekranu za pomocą pakietów testów

Od wersji 9.5.0-alpha03 wtyczki Androida do obsługi Gradle (AGP) i silnika testowania zrzutów ekranu podglądu Compose 0.0.1-alpha16 testowanie zrzutów ekranu jest zintegrowane z natywną strukturą zestawów testów AGP.

To podejście zastępuje samodzielną wtyczkę zrzutów ekranu (com.android.compose.screenshot). Zalecamy stosowanie zestawów testów AGP z tych powodów:

• Natywny cykl życia zadania Gradle: testy zrzutów ekranu są bezpośrednio zintegrowane ze standardowymi cyklami życia testów Gradle i AGP, co zwiększa izolację zadań i niezawodność wykonywania testów.
• Obsługa wielu wariantów i niestandardowych zestawów testów: w ramach jednego modułu możesz utworzyć wiele różnych zestawów testów zrzutów ekranu (np. screenshotTest, uiTests lub smokeTests) i kierować je na konkretne warianty kompilacji (np. demoDebug lub release), zamiast ograniczać się do jednego wstępnie skonfigurowanego zbioru źródeł.
• Większa wydajność i izolacja kompilacji: zestawy testów AGP korzystają z wbudowanych przekształceń artefaktów (takich jak wyodrębnianie środowiska wykonawczego Layoutlib) i izolowanego ładowania klas, z pełną obsługą buforowania konfiguracji Gradle i izolacji projektu.

Wymagania

Aby używać testowania zrzutów ekranu w Compose w przypadku pakietów testów, upewnij się, że Twoje środowisko spełnia te wymagania:

• Android Studio Rabbit 1 Canary 4 lub nowszy.
• Wtyczka Androida do obsługi Gradle (AGP) w wersji 9.5.0-alpha03 lub nowszej.
• Silnik zrzutów ekranu Compose w wersji 0.0.1-alpha16 lub nowszej.
• JDK w wersji 17 lub nowszej.
• Compose jest włączony w Twoim projekcie. Zalecamy włączenie Compose za pomocą wtyczki Gradle kompilatora Compose.

Ustawienia i konfiguracja

Aby skonfigurować testowanie zrzutów ekranu w Compose za pomocą pakietów testów, wykonaj te czynności:

1. Włączanie flag eksperymentalnych

W pliku gradle.properties w katalogu głównym projektu włącz testowanie zrzutów ekranu i obsługę pakietu testów:

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

2. Skonfiguruj zestaw testów w pliku build.gradle.kts.

W pliku build.gradle.kts modułu zdefiniuj pakiet testów zrzutów ekranu w bloku testOptions:

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. Tworzenie testowego zbioru źródeł

Utwórz dedykowany katalog zbioru źródeł pasujący do nazwy pakietu:

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

Na przykład w przypadku pakietu o nazwie screenshotTest:

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

4. Definiowanie testów podglądu komponentów

Dodaj do funkcji kompozycyjnych adnotacje @PreviewTest i standardowe adnotacje @Preview lub adnotacje do wielu podglądów:

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

Przeprowadzanie testów zrzutów ekranu

Zestawy testów AGP generują dedykowane zadania Gradle na podstawie nazwy zestawu, celu i wariantów.

1. Generowanie lub aktualizowanie obrazów referencyjnych

Renderuj podglądy komponentów i zapisuj referencyjne obrazy bazowe:

• Linux i macOS: ./gradlew update{SuiteName}{Target}{Variant}TestSuite (np. ./gradlew updateScreenshotTestDefaultDemoDebugTestSuite)
• Windows: gradlew updateScreenshotTestDefaultDemoDebugTestSuite

Obrazy referencyjne są generowane i zapisywane w tym miejscu:

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

2. Sprawdzanie i przeprowadzanie testów

Renderuj nowe zrzuty ekranu i porównuj je z obrazami referencyjnymi:

• Linux i macOS: ./gradlew test{SuiteName}{Target}{Variant}TestSuite (np. ./gradlew testScreenshotTestDefaultDemoDebugTestSuite)
• Windows: gradlew testScreenshotTestDefaultDemoDebugTestSuite

Sprawdzanie raportów z testów

Jeśli zostaną wykryte różnice lub testy zakończą się niepowodzeniem, AGP wygeneruje raport z testu w formacie HTML.

• Lokalizacja raportu: {module}/build/reports/tests/{taskName}/index.html (np.app/build/reports/tests/testScreenshotTestDefaultDemoDebugTestSuite/index.html)

Zaktualizowany raport zawiera:

• Karta metadanych nagłówka: wyświetla nazwę testu, metodę podglądu, wariant, pakiet i plakietkę stanu.
• Kategoryzacja błędów: wyraźnie oznacza błędy Reference Image Missing,Image Size Mismatch lub Pixel Mismatch z możliwością skopiowania śladów stosu.
• Dynamiczne porównanie wizualne: podkreśla subtelne modyfikacje z mniejszą intensywnością, a większe zmiany z wysokim kontrastem, aby zapobiec „pochłanianiu” zagnieżdżonych elementów.

Migracja ze starszej samodzielnej wtyczki

Aby przejść ze starszej, samodzielnej wtyczki do zrzutów ekranu na zestawy testów AGP, zaktualizuj konfigurację Gradle i polecenia zadań.

Porównanie DSL konfiguracji kompilacji

Starsza wersja samodzielnej wtyczki (wycofana)

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

Zestawy testów AGP (zalecane)

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

Mapowanie zadań i ścieżek