Testowanie zrzutu ekranu w podglądzie tworzenia

Testowanie zrzutów ekranu to skuteczny sposób na sprawdzenie, jak interfejs użytkownika wygląda dla użytkowników. Narzędzie do testowania zrzutów ekranu podglądu funkcji Compose łączy prostotę i funkcje podglądów funkcji do komponowania ze wzrostem produktywności wynikającym z przeprowadzania testów zrzutów ekranu po stronie hosta. Podgląd w widoku tworzenia Testowanie zrzutów ekranu zostało zaprojektowane tak, aby było równie łatwe w użyciu jak podglądy komponentów.

Test zrzutu ekranu to test automatyczny, który robi zrzut ekranu fragmentu interfejsu, a następnie porównuje go z wcześniej zatwierdzonym obrazem referencyjnym. Jeśli obrazy nie pasują do siebie, test zakończy się niepowodzeniem i wygeneruje raport HTML, który pomoże Ci porównać obrazy i znaleźć różnice.

Za pomocą narzędzia do testowania zrzutów ekranu podglądu kompozycji możesz:

• Użyj @PreviewTest, aby utworzyć testy zrzutów ekranu dla istniejących lub nowych podglądów komponentów.
• Generuj obrazy referencyjne na podstawie tych podglądów.
• Wygeneruj raport HTML, który po wprowadzeniu zmian w kodzie będzie zawierać informacje o zmianach w tych podglądach.
• Używaj parametrów @Preview, takich jak uiMode lub fontScale, oraz wielu podglądów, aby skalować testy.
• Podziel testy na moduły za pomocą nowego screenshotTestzestawu źródeł.

Wymagania

Aby korzystać z testowania zrzutów ekranu podglądu funkcji Compose, musisz mieć:

• Wtyczka Androida do obsługi Gradle w wersji 8.5.0 lub nowszej.
• Kotlin w wersji 1.9.20 lub nowszej. Zalecamy używanie Kotlin w wersji 2.0 lub nowszej, aby móc korzystać z wtyczki Gradle kompilatora Compose.
• JDK 23 lub starsza.

• Compose jest włączony w Twoim projekcie. Zalecamy włączenie Compose za pomocą wtyczki Gradle kompilatora Compose.

Konfiguracja

Aby włączyć to narzędzie, wykonaj te czynności:

1. Włącz eksperymentalną właściwość w pliku gradle.properties projektu.

         android.experimental.enableScreenshotTest=true
       

2. W bloku android {} pliku build.gradle.kts na poziomie modułu włącz flagę eksperymentalną, aby używać zestawu źródeł screenshotTest.

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

3. Dodaj do projektu wtyczkę com.android.compose.screenshot w wersji 0.0.1-alpha11.
   1. Dodaj wtyczkę do pliku katalogów wersji:

                [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. W pliku build.gradle.kts na poziomie modułu dodaj wtyczkę w bloku plugins {}:

                plugins {
                    alias(libs.plugins.screenshot)
                }
              

4. Dodaj zależności screenshot-validation-api i ui-tooling.
   1. Dodaj je do katalogów wersji:

                [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. Dodaj je do pliku build.gradle.kts na poziomie modułu:

                dependencies {
                  screenshotTestImplementation(libs.screenshot.validation.api)
                  screenshotTestImplementation(libs.androidx.ui.tooling)
                }
              

Wyznaczanie podglądów kompozycyjnych do użycia w testach zrzutów ekranu

Aby wskazać podglądy funkcji kompozycyjnych, których chcesz użyć w testach zrzutów ekranu, oznacz je adnotacją @PreviewTest. Podglądy muszą znajdować się w nowym zestawie źródeł screenshotTest, np. app/src/screenshotTest/kotlin/com/example/yourapp/ExamplePreviewScreenshotTest.kt.

W tym pliku lub w innych plikach utworzonych w tym samym zestawie źródeł możesz dodać więcej funkcji kompozycyjnych lub podglądów, w tym podglądów wielokrotnych.

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

Generowanie obrazów referencyjnych

Po skonfigurowaniu klasy testowej musisz wygenerować obrazy referencyjne dla każdej wersji podglądu. Obrazy referencyjne są używane do identyfikowania zmian w późniejszym czasie, po wprowadzeniu zmian w kodzie. Aby wygenerować obrazy referencyjne na potrzeby testów zrzutów ekranu podglądu komponentu, uruchom to zadanie Gradle:

• Linux i macOS: ./gradlew updateDebugScreenshotTest (./gradlew :{module}:update{Variant}ScreenshotTest)
• Windows: gradlew updateDebugScreenshotTest (gradlew :{module}:update{Variant}ScreenshotTest)

Po zakończeniu zadania znajdź obrazy referencyjne w folderze app/src/screenshotTestDebug/reference ({module}/src/screenshotTest{Variant}/reference).

Generowanie raportu testowego

Gdy obrazy referencyjne będą już dostępne, uruchom zadanie weryfikacji, aby zrobić nowy zrzut ekranu i porównać go z obrazem referencyjnym:

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

Zadanie weryfikacji tworzy raport HTML w lokalizacji {module}/build/reports/screenshotTest/preview/{variant}/index.html.

Znane problemy

Aktualną listę znanych problemów znajdziesz w komponencie narzędzia do śledzenia problemów. Inne opinie i problemy zgłaszaj za pomocą narzędzia do śledzenia problemów.

Aktualizacje wersji

0.0.1-alpha11

Ta wersja wprowadza:

• Zgodność z wtyczką Androida do obsługi Gradle (AGP) w wersji 8.13.
• Dodano obsługę analizowania rysunków XML z wartościami dziesiętnymi niezależnie od ustawień regionalnych komputera hosta.
• W przypadku maszyny hosta korzystającej z JDK 24 lub nowszej zostanie wybrana zgodna wersja JDK (11–23), o ile jest zainstalowana.

0.0.1-alpha10

Ta wersja wprowadza:

• Od tej wersji musisz oznaczyć wszystkie funkcje w wersji zapoznawczej adnotacją @PreviewTest. Podglądy bez adnotacji nie będą wykonywane.

• Katalog obrazów referencyjnych został zmieniony z:{module}/src/{variant}/screenshotTest/reference na:{module}/src/screenshotTest{Variant}/reference. Dzięki temu wygenerowane obrazy referencyjne nie będą częścią kodu produkcyjnego, a struktura katalogów będzie zgodna z strukturą katalogów innych typów testów.

• Zadanie {variant}PreviewScreenshotRender zostanie usunięte. Renderowanie obrazów jest przenoszone do silnika testowego JUnit.

• update{Variant}ScreenshotTest porówna nowe obrazy renderowane z obrazami referencyjnymi przed aktualizacją. Aktualizuje tylko obrazy, w których różnice przekraczają określony próg. Usunięto flagę --updateFilter wiersza poleceń.

0.0.1-alpha06

Ta wersja wprowadza:

Próg różnicy obrazu: to nowe ustawienie globalnego progu pozwoli Ci uzyskać większą kontrolę nad porównywaniem zrzutów ekranu. Aby skonfigurować moduł, zaktualizuj plik build.gradle.kts:

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

Ten próg zostanie zastosowany do wszystkich testów zrzutów ekranu zdefiniowanych w module.

• Poprawki błędów: naprawiliśmy niektóre błędy renderowania w Compose i dodaliśmy obsługę pustych kompozycji.
• Ulepszenia wydajności: algorytm porównywania obrazów został zaktualizowany, aby działać szybciej.