Ta strona została przetłumaczona przez Cloud Translation API.

Testowanie zrzutu ekranu w podglądzie tworzenia

Testowanie zrzutów ekranu to skuteczny sposób na sprawdzenie, jak interfejs użytkownika wygląda z perspektywy użytkowników. Narzędzie do testowania zrzutów ekranu w podglądzie funkcji Compose łączy prostotę i funkcje podglądów funkcji kompozycyjnych 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 w widoku tworzenia.

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 screenshotTest źródła.

Wymagania

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

wtyczkę Androida do obsługi Gradle w wersji 8.5.0-beta01 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. To narzędzie nie jest zgodne z JDK 24 ani nowszymi wersjami ze względu na zależność od Menedżera zabezpieczeń Java, który został usunięty w nowszych wersjach JDK.
Compose jest włączony w Twoim projekcie. Zalecamy włączenie Compose za pomocą wtyczki Gradle kompilatora Compose.

Uwaga: jeśli nie możesz użyć wtyczki Gradle Compose Compiler, możesz włączyć Compose, deklarując bezpośrednio zależność od Compose Compiler. Upewnij się, że używasz kotlinCompilerExtensionVersion w wersji 1.5.4 lub nowszej.

Konfiguracja

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

Dodaj do projektu wtyczkę com.android.compose.screenshot w wersji 0.0.1-alpha10.

Dodaj wtyczkę do pliku katalogów wersji:

[versions]
agp = "8.11.0-alpha06"
kotlin = "2.1.20"
screenshot = "0.0.1-alpha10"

[plugins]
screenshot = { id = "com.android.compose.screenshot", version.ref = "screenshot"}

W pliku build.gradle.kts na poziomie modułu dodaj wtyczkę w bloku plugins {}:
```
plugins {
    alias(libs.plugins.screenshot)
}
```

Włącz eksperymentalną właściwość w pliku gradle.properties projektu.
```
android.experimental.enableScreenshotTest=true
```
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
}
```

Dodaj zależności screenshot-validation-api i ui-tooling.

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

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 kompozycyjne, których chcesz użyć do testów 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

Informacje o wersji i zmiany w bieżących wersjach.

0.0.1-alpha10

W tej wersji wprowadziliśmy:

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 zostało przeniesione 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

W tej wersji wprowadziliśmy:

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 będzie stosowany 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: zaktualizowano algorytm porównywania obrazów, aby działał szybciej.