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

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

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

С помощью инструмента тестирования скриншотов Compose Preview вы можете:

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

Требования

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

  • Плагин Android Gradle 8.5.0 или выше.
  • Kotlin 1.9.20 или выше. Мы рекомендуем использовать Kotlin 2.0 или выше, чтобы использовать плагин Gradle Compose Compiler.
  • JDK 23 или ниже.

  • Включён Compose для вашего проекта. Мы рекомендуем включить Compose с помощью плагина Gradle Compose Compiler .

Настраивать

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

  1. Включите экспериментальное свойство в файле gradle.properties вашего проекта. 
          android.experimental.enableScreenshotTest=true
  2. В блоке android {} файла build.gradle.kts на уровне модуля включите экспериментальный флаг, чтобы использовать исходный набор screenshotTest . 
          android {
          experimentalProperties["android.experimental.enableScreenshotTest"] = true
      }
  3. Добавьте в свой проект плагин com.android.compose.screenshot версии 0.0.1-alpha11 .
    1. Добавьте плагин в файл каталогов версий: 
                [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. В файле build.gradle.kts на уровне модуля добавьте плагин в блок plugins {} : 
                plugins {
              alias(libs.plugins.screenshot)
          }
  4. Добавьте зависимости screenshot-validation-api и ui-tooling .
    1. Добавьте их в свои каталоги версий: 
                [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. Добавьте их в файл 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-альфа11

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

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

0.0.1-альфа10

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

  • Начиная с этой версии, все функции предварительного просмотра необходимо помечать аннотацией @PreviewTest . Предварительные просмотры без этой аннотации выполняться не будут.

  • Каталог эталонных изображений изменён с {module}/src/{variant}/screenshotTest/reference на {module}/src/screenshotTest{Variant}/reference . Это сделано для того, чтобы сгенерированные эталонные изображения не попали в производственный код и соответствовали структуре каталогов других типов тестов.

  • Задача {variant}PreviewScreenshotRender удалена. Рендеринг изображений перенесён в JUnit Test Engine.

  • Задача update{Variant}ScreenshotTest будет сравнивать новые изображения рендеринга с эталонными перед обновлением. Она будет обновлять только те изображения, различия между которыми превышают указанное пороговое значение. Флаг командной строки --updateFilter был удалён.

0.0.1-альфа06

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

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

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

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

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