Эта страница переведена с помощью Cloud Translation API.

Тестирование создания скриншота предварительного просмотра

Тестирование с помощью скриншотов — эффективный способ проверить, как ваш пользовательский интерфейс выглядит для пользователей. Инструмент Compose Preview Screenshot Testing сочетает в себе простоту и функциональность составных предварительных просмотров с преимуществами повышения производительности за счет проведения тестов скриншотов на стороне хоста. Инструмент Compose Preview Screenshot Testing разработан таким образом, чтобы быть таким же простым в использовании, как и составные предварительные просмотры.

Тест скриншота — это автоматизированный тест, который делает снимок экрана элемента пользовательского интерфейса и сравнивает его с ранее утвержденным эталонным изображением. Если изображения не совпадают, тест завершается неудачей и создает HTML-отчет, который поможет вам сравнить и найти различия.

С помощью инструмента «Предварительный просмотр скриншотов при создании контента» вы можете:

Используйте @PreviewTest для создания тестов скриншотов для существующих или новых составных предварительных просмотров.
Создайте эталонные изображения на основе этих компонуемых предварительных просмотров.
Создайте HTML-отчет, который отобразит изменения в этих предварительных просмотрах после внесения изменений в код.
Используйте параметры @Preview , такие как uiMode или fontScale , а также множественный предварительный просмотр, чтобы масштабировать ваши тесты.
Создайте модульную структуру для ваших тестов с помощью нового набора исходных файлов screenshotTest .

Требования

Для использования функции предварительного просмотра скриншотов в Compose Preview Screenshot Testing вам потребуется следующее:

Плагин Android Gradle версии 8.5.0 или выше.
Kotlin 1.9.20 или выше. Мы рекомендуем использовать Kotlin 2.0 или выше, чтобы вы могли использовать плагин Compose Compiler Gradle.
JDK 23 или ниже.
Включите Compose для вашего проекта. Мы рекомендуем включить Compose с помощью плагина Compose Compiler Gradle .
Примечание: Если вы не можете использовать плагин Compose Compiler Gradle, вы можете включить Compose, объявив зависимость от Compose Compiler напрямую . Убедитесь, что вы используете версию kotlinCompilerExtensionVersion 1.5.4 или выше.

Настраивать

Чтобы активировать инструмент, выполните следующие действия:

Включите экспериментальное свойство в файле gradle.properties вашего проекта.
```
      android.experimental.enableScreenshotTest=true
    
```
В блоке android {} файла build.gradle.kts на уровне модуля включите флаг `experimental`, чтобы использовать набор исходных файлов screenshotTest .
```
      android {
          experimentalProperties["android.experimental.enableScreenshotTest"] = true
      }
    
```

Добавьте в свой проект плагин com.android.compose.screenshot версии 0.0.1-alpha12 .

Добавьте плагин в файл каталогов версий:

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

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

В файле build.gradle.kts , расположенном на уровне модуля, добавьте плагин в блок plugins {} :
```
          plugins {
              alias(libs.plugins.screenshot)
          }
        
```

Добавьте зависимости screenshot-validation-api и ui-tooling .

Добавьте их в свои каталоги версий:

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

Добавьте их в файл build.gradle.kts на уровне модуля:

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

Назначьте компонуемые предварительные просмотры для использования в тестах скриншотов.

Чтобы указать компонуемые предварительные просмотры, которые вы хотите использовать для тестов скриншотов, пометьте их аннотацией @PreviewTest . Предварительные просмотры должны находиться в новом наборе исходных файлов screenshotTest , например app/src/screenshotTest/kotlin/com/example/yourapp/ExamplePreviewScreenshotTest.kt .

В этот файл или другие файлы, созданные в том же наборе исходных файлов, можно добавить больше элементов для компоновки и/или предварительного просмотра, включая множественный предварительный просмотр.

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

Сгенерировать эталонные изображения

После создания тестового класса необходимо сгенерировать эталонные изображения для каждого предварительного просмотра. Эти эталонные изображения используются для идентификации изменений в дальнейшем, после внесения изменений в код. Чтобы сгенерировать эталонные изображения для ваших составных тестов с предварительным просмотром скриншотов, выполните следующую задачу Gradle:

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

После завершения задачи найдите эталонные изображения в app/src/screenshotTestDebug/reference ( {module}/src/screenshotTest{Variant}/reference ).

Сгенерировать отчет о тестировании

После создания эталонных изображений запустите задачу проверки, чтобы сделать новый снимок экрана и сравнить его с эталонным изображением:

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

Задача проверки создает HTML-отчет по адресу {module}/build/reports/screenshotTest/preview/{variant}/index.html .

Известные проблемы

Актуальный список известных проблем можно найти в компоненте отслеживания ошибок инструмента. Сообщайте о любых других проблемах и отзывах через систему отслеживания ошибок .

Обновления релизов

0.0.1-alpha12

В этом релизе представлены:

Совместимость с плагином Android Gradle (AGP) 9.0.
Поддержка запуска тестов скриншотов в JDK 24 и выше.
Поддерживается настройка максимального размера кучи.
Исправлены ошибки рендеринга и повышена стабильность тестов.
Улучшена отчетность за счет включения процентных различий и других метаданных, относящихся к новым и эталонным изображениям.

0.0.1-alpha11

В этом релизе представлены:

Совместимость с плагином Android Gradle (AGP) 8.13.
Добавлена поддержка анализа XML-файлов с десятичными значениями независимо от локали хост-машины.
Для хост-машины, использующей JDK 24 или выше, будет выбрана совместимая версия JDK (11-23), при условии, что она установлена.

0.0.1-alpha10

В этом релизе представлены:

Начиная с этой версии, необходимо помечать все функции предварительного просмотра аннотацией @PreviewTest . Предварительный просмотр без этой аннотации выполняться не будет.
Каталог эталонных изображений изменен с {module}/src/{variant}/screenshotTest/reference на {module}/src/screenshotTest{Variant}/reference . Это сделано для того, чтобы сгенерированные эталонные изображения не попали в производственный код, и для соответствия структуре каталогов других типов тестов.
Задача {variant}PreviewScreenshotRender удалена. Рендеринг изображений перенесен в JUnit Test Engine.
Задача update{Variant}ScreenshotTest будет сравнивать новые изображения рендеринга с эталонными изображениями перед обновлением. Она будет обновлять только те изображения, различия между которыми превышают указанный порог. Флаг командной строки --updateFilter был удален.

0.0.1-alpha06

В этом релизе представлены:

Пороговое значение разницы изображений: Эта новая глобальная настройка порогового значения позволит вам более точно контролировать сравнение скриншотов. Для настройки обновите файл build.gradle.kts вашего модуля:

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

Этот пороговый уровень будет применяться ко всем тестам скриншотов, определенным в модуле.

Исправлены ошибки: исправлены некоторые ошибки рендеринга Compose и добавлена поддержка пустого Compose.
Улучшения производительности: алгоритм сравнения изображений был обновлен для повышения скорости работы.