Тестирование скриншотов с помощью наборов тестов

Начиная с версии 9.5.0-alpha03 плагина Android Gradle (AGP) и версии 0.0.1-alpha16 инструмента Compose Preview Screenshot Testing, тестирование скриншотов интегрировано с нативным фреймворком наборов тестов AGP.

Этот подход заменяет отдельный плагин для скриншотов (com.android.compose.screenshot). Мы рекомендуем использовать наборы тестов AGP по следующим причинам:

  • Встроенный жизненный цикл задач Gradle. Тестирование скриншотов интегрировано непосредственно в стандартные жизненные циклы тестирования Gradle и AGP, что улучшает изоляцию задач и надежность выполнения тестов.
  • Поддержка нескольких вариантов и пользовательских наборов. Вы можете создать несколько отдельных наборов тестов скриншотов (например, screenshotTest, uiTests или smokeTests) в одном модуле и настроить таргетинг на определенные варианты сборки (например, demoDebug или release), а не ограничиваться одним предварительно настроенным набором исходных файлов.
  • Повышенная производительность и изоляция сборок. Наборы тестов AGP используют встроенные преобразования артефактов (например, извлечение среды выполнения Layoutlib) и изолированную загрузку классов с полной поддержкой кеширования конфигурации Gradle и изоляции проектов.

Требования

Чтобы использовать Compose Screenshot Testing с наборами тестов, убедитесь, что ваша среда соответствует следующим требованиям:

  • Android Studio Rabbit 1 Canary 4 или более поздней версии.
  • Плагин Android Gradle (AGP) версии 9.5.0-alpha03 или более поздней.
  • Compose Screenshot Engine версии 0.0.1-alpha16 или выше.
  • JDK версии 17 или более поздней.
  • Compose включен для вашего проекта. Рекомендуем включить Compose с помощью плагина Compose Compiler Gradle.

Настройка и конфигурация

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

1. Включить экспериментальные флаги

В корневом файле gradle.properties проекта включите тестирование скриншотов и поддержку набора тестов:

android.experimental.enableScreenshotTest=true
android.experimental.testSuiteSupport=true

2. Настройте набор тестов в файле build.gradle.kts.

В файле build.gradle.kts модуля определите набор тестов скриншотов в блоке testOptions:

android {
    testOptions {
        screenshotTests.create("screenshotTest") { // suiteName can be customized (for example, "uiTests")
            engineVersion = "0.0.1-alpha16"
            targetVariants.add("demoDebug") // Add specific variants to test

            dependencies {
                implementation(libs.androidx.compose.ui.tooling)
                implementation("com.android.tools.screenshot:screenshot-validation-api:0.0.1-alpha16")
            }
        }
    }
}

3. Создайте набор исходных файлов для тестирования

Создайте каталог набора исходных файлов, соответствующий названию набора:

{module}/src/{suiteName}/kotlin/

Например, для набора screenshotTest:

feature/foryou/impl/src/screenshotTest/kotlin/com/example/app/ForYouScreenTest.kt

4. Как определить тесты предварительного просмотра composable-функций

Добавьте к composable-функциям аннотации @PreviewTest и стандартные аннотации @Preview или аннотации Multi Preview:

package com.example.app

import androidx.compose.runtime.Composable
import androidx.compose.ui.tooling.preview.Preview
import com.android.tools.screenshot.PreviewTest
import com.example.app.ui.theme.AppTheme

@PreviewTest
@Preview(showBackground = true)
@Composable
fun ForYouScreenPreview() {
    AppTheme {
        ForYouScreen(isSyncing = false)
    }
}

Запуск тестов скриншотов

Наборы тестов AGP генерируют выделенные задачи Gradle на основе названия набора, цели и вариантов.

1. Как создать или обновить референсные изображения

Отрисуйте предварительные версии composable-функций и сохраните эталонные изображения:

  • Linux и macOS: ./gradlew update{SuiteName}{Target}{Variant}TestSuite (например, ./gradlew updateScreenshotTestDefaultDemoDebugTestSuite)
  • Windows: gradlew updateScreenshotTestDefaultDemoDebugTestSuite

Референсные изображения создаются и сохраняются в следующих папках:

{module}/src/{suiteName}{Target}{Variant}/reference/

2. Проверка и тестирование

Создайте новые скриншоты и сравните их с референсными изображениями:

  • Linux и macOS: ./gradlew test{SuiteName}{Target}{Variant}TestSuite (например, ./gradlew testScreenshotTestDefaultDemoDebugTestSuite)
  • Windows: gradlew testScreenshotTestDefaultDemoDebugTestSuite

Как изучить отчеты о тестировании

Если обнаружены различия или тесты не пройдены, AGP создает отчет о тестировании в формате HTML.

  • Местоположение отчета: {module}/build/reports/tests/{taskName}/index.html (например, app/build/reports/tests/testScreenshotTestDefaultDemoDebugTestSuite/index.html)

Обновленный отчет содержит следующие данные:

  • Карточка метаданных заголовка. На ней показывается название теста, метод предварительного просмотра, вариант, набор и значок статуса.
  • Категоризация ошибок. Четко помечает Reference Image Missing, Image Size Mismatch или Pixel Mismatch с помощью копируемых трассировок стека.
  • Динамическое визуальное сравнение. Незначительные изменения выделяются менее интенсивно, а значительные – более контрастно, чтобы не упустить вложенные элементы.

Как перейти с устаревшего отдельного плагина

Чтобы перейти с устаревшего отдельного плагина для скриншотов на наборы тестов AGP, обновите конфигурацию Gradle и команды задач.

Сравнение DSL конфигурации сборки

Устаревший отдельный плагин (не поддерживается)

// In build.gradle.kts
plugins {
    alias(libs.plugins.screenshot)
}

dependencies {
    screenshotTestImplementation(libs.androidx.compose.ui.tooling)
    screenshotTestImplementation("com.android.tools.screenshot:screenshot-validation-api:0.0.1-alpha16")
}

// In build.gradle.kts
android {
    testOptions {
        screenshotTests.create("screenshotTest") {
            engineVersion = "0.0.1-alpha16"
            targetVariants.add("demoDebug")

            dependencies {
                implementation(libs.androidx.compose.ui.tooling)
                implementation("com.android.tools.screenshot:screenshot-validation-api:0.0.1-alpha16")
            }
        }
    }
}

Сопоставление задач и путей

Концепция Устаревшие настройки (поддержка прекращена) Наборы тестов AGP (рекомендуется)
Как изменить задачу ./gradlew updateDebugScreenshotTest ./gradlew update{SuiteName}{Target}{Variant}TestSuite
Тестовое задание ./gradlew validateDebugScreenshotTest ./gradlew test{SuiteName}{Target}{Variant}TestSuite
Путь к цифровому отпечатку src/screenshotTestDebug/reference src/{suiteName}{Target}{Variant}/reference
Путь к отчету build/reports/screenshotTest/debug/ build/reports/tests/{taskName}/