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

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

android skills add testing-setup

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

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

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

Интеграция с IDE

Вы можете использовать инструмент тестирования скриншотов Compose Preview, вручную запуская базовые задачи Gradle (updateScreenshotTest и validateScreenshotTest), но в Android Studio Otter 3 Feature Drop Canary 4 реализована полная интеграция с IDE. Это позволяет генерировать референсные изображения, запускать тесты и анализировать ошибки валидации прямо в IDE. Вот некоторые из ключевых функций:

• Значки на полях редактора. Теперь вы можете запускать тесты или обновлять референсные изображения прямо из исходного кода. На полях рядом с composable-функциями и классами, аннотированными с помощью @PreviewTest, появятся зеленые значки запуска.
  • Проведите тестирование скриншотов. Выполняйте тесты для одной функции или для всего класса.
  • Добавьте или обновите референсные изображения. Запустите процесс обновления для выбранной области.

• Интерактивное управление цифровыми отпечатками. Обновлять референсные изображения теперь безопаснее и проще.
  • Диалоговое окно для генерирования нового референсного изображения. Вместо выполнения массовой задачи Gradle в новом диалоговом окне можно выбрать, какие именно предварительные версии нужно создать или обновить.
  • Посмотрите варианты. В диалоговом окне перечислены все варианты предварительного просмотра (например, светлая или темная тема, разные устройства). Вы можете выбрать или очистить определенные элементы перед созданием изображений.

• Интегрированные результаты тестирования и средство просмотра различий. Просматривайте результаты, не выходя из IDE.
  • Единая панель запуска. Результаты тестирования скриншотов появляются в стандартном окне инструмента Run (Запуск). Тесты сгруппированы по классам и функциям, а их статус (пройден или нет) четко обозначен.
  • Инструмент Visual Diff. Если тест не пройден, на вкладке Скриншот можно сравнить изображения Эталон, Фактическое и Разница.
  • Подробные атрибуты. На вкладке Attributes (Атрибуты) представлены метаданные о неудачных тестах, включая процент совпадения, размеры изображения и конкретную конфигурацию предварительного просмотра (например, uiMode или fontScale).

• Гибкая область тестирования. Теперь вы можете выполнять тестирование скриншотов с различными областями действия прямо из окна Project (Проект). Нажмите правой кнопкой мыши на модуль, каталог, файл или класс, чтобы запустить тестирование скриншотов для выбранного элемента.

Требования

Чтобы использовать тестирование скриншотов предварительного просмотра Compose через полную интеграцию с IDE, ваш проект должен соответствовать следующим требованиям:

• Android Studio Panda 1 Canary 4 или более поздней версии.
• Плагин Android Gradle (AGP) версии 9.0 или более поздней.
• Плагин Compose Preview Screenshot Testing версии 0.0.1-alpha16 или более поздней.
• Kotlin 2.2.10 или более поздней версии.
• JDK версии 17 или выше.
• Функция Compose включена для вашего проекта. Рекомендуем включить Compose с помощью плагина Compose Compiler Gradle.

Если вы хотите использовать только базовые задачи Gradle без интеграции с IDE, требования будут следующими:

• Плагин Android Gradle (AGP) версии 8.5.0 или более поздней.
• Плагин Compose Preview Screenshot Testing версии 0.0.1-alpha16 или более поздней.
• Kotlin 1.9.20 или более поздней версии. Рекомендуем использовать Kotlin 2.0 или более поздней версии, чтобы вы могли использовать плагин Compose Compiler Gradle.
• JDK версии 17 или выше.
• Функция Compose включена для вашего проекта. Рекомендуем включить Compose с помощью плагина Compose Compiler Gradle.

Настроить

И встроенный инструмент, и задачи Gradle используют плагин Compose Preview Screenshot Testing. Для этого Выполните следующие действия:

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-alpha16.

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

      [versions]
      agp = "9.0.0-rc03"
      kotlin = "2.2.10"
      screenshot = "0.0.1-alpha16"
      
      [plugins]
      screenshot = { id = "com.android.compose.screenshot", version.ref = "screenshot"}
      

   2. Добавьте плагин в блок plugins {} файла build.gradle.kts на уровне модуля:

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

Как указать, какие предварительные версии composable-функций использовать для тестирования скриншотов

Чтобы указать, какие composable-функции предварительного просмотра вы хотите использовать для тестирования скриншотов, пометьте их аннотацией @PreviewTest. Предварительные версии должны находиться в новом наборе исходных файлов screenshotTest, например:

app/src/screenshotTest/kotlin/com/example/yourapp/ ExamplePreviewScreenshotTest.kt

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

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

Создание референсных изображений

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

android studio render-compose-preview

В IDE

Нажмите на значок на полях рядом с функцией @PreviewTest и выберите Add/Update Reference Images (Добавить/обновить референсные изображения). Выберите нужные варианты и нажмите Добавить.

С помощью задач Gradle

Выполните следующую задачу 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).

Как создать тестовый отчет

После того как референсные изображения будут созданы, сгенерируйте тестовый отчет, следуя инструкциям в этом разделе для интеграции IDE или задач Gradle.

В IDE

Нажмите на значок рядом с функцией @PreviewTest и выберите Run 'ScreenshotTests' (Запустить ScreenshotTests).

Если тест не пройден, нажмите на его название на панели Run (Запуск). Выберите вкладку Скриншот, чтобы изучить различия между изображениями, используя встроенные элементы управления масштабированием и панорамированием.

С помощью задач Gradle

Запустите задачу проверки, чтобы сделать новый скриншот и сравнить его с референсным изображением:

• 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.

Устранение неполадок

Тестирование скриншотов предварительного просмотра Compose выполняется на стороне хоста и может требовать много памяти. Чтобы увеличить максимальный размер кучи для тестовой JVM, добавьте в файл gradle.properties следующее свойство:

android.compose.screenshot.maxHeapSize=4g

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

• Kotlin Multiplatform (KMP). И интегрированная среда разработки, и базовый плагин разработаны исключительно для проектов для Android. Они не поддерживают цели, не связанные с Android, в проектах KMP.

Полный список известных проблем можно найти в системе отслеживания ошибок. Если вы хотите оставить отзыв или сообщить о проблеме, воспользуйтесь системой отслеживания ошибок.

Обновления

Полный список изменений можно найти в примечаниях к выпуску.