Teste de captura de tela com pacotes de teste

A partir do Plug-in do Android para Gradle (AGP) 9.5.0-alpha03 e do mecanismo de teste de captura de tela da prévia do Compose 0.0.1-alpha16, o teste de captura de tela é integrado ao framework nativo de conjuntos de testes do AGP.

Essa abordagem substitui o plug-in de captura de tela independente (com.android.compose.screenshot). Recomendamos adotar conjuntos de testes do AGP pelos seguintes motivos:

• Ciclo de vida nativo da tarefa do Gradle: os testes de captura de tela são integrados diretamente aos ciclos de vida de teste padrão do Gradle e do AGP, melhorando o isolamento de tarefas e a confiabilidade da execução do teste.
• Suporte a várias variantes e pacotes personalizados: é possível criar vários pacotes de teste de captura de tela distintos (como screenshotTest, uiTests ou smokeTests) em um único módulo e segmentar variantes de build específicas (como demoDebug ou release), em vez de ficar restrito a um único conjunto de origem pré-configurado.
• Melhoria na performance e no isolamento do build: os conjuntos de testes do AGP usam transformações de artefato integradas (como extração de tempo de execução do Layoutlib) e carregamento de classes isolado, com suporte total ao cache de configuração do Gradle e ao isolamento de projetos.

Requisitos

Para usar o Compose Screenshot Testing com conjuntos de testes, verifique se o ambiente atende aos seguintes requisitos:

• Android Studio Rabbit 1 Canary 4 ou versões mais recentes.
• Plug-in do Android para Gradle (AGP) versão 9.5.0-alpha03 ou mais recente.
• Versão 0.0.1-alpha16 ou mais recente do Compose Screenshot Engine.
• JDK versão 17 ou mais recente.
• O Compose está ativado para seu projeto. Recomendamos ativar o Compose usando o plug-in do Gradle do compilador do Compose.

Configuração

Para configurar o teste de captura de tela do Compose com conjuntos de testes, siga estas etapas:

1. Ativar flags experimentais

No arquivo gradle.properties raiz do projeto, ative o teste de captura de tela e o suporte ao conjunto de testes:

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

2. Configurar o conjunto de testes no arquivo build.gradle.kts

No arquivo build.gradle.kts do módulo, defina um conjunto de testes de captura de tela no bloco 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. Criar o conjunto de origem de teste

Crie um diretório de conjunto de origem dedicado que corresponda ao nome do seu pacote:

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

Por exemplo, para uma suíte chamada screenshotTest:

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

4. Definir testes de prévia combináveis

Adicione anotações aos elementos combináveis com @PreviewTest e @Preview padrão ou anotações de visualização múltipla:

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

Executar testes de captura de tela

Os conjuntos de testes do AGP geram tarefas dedicadas do Gradle com base no nome, no destino e nas variantes do conjunto.

1. Gerar ou atualizar imagens de referência

Renderize prévias combináveis e armazene as imagens de referência de base de ouro:

• Linux e macOS: ./gradlew update{SuiteName}{Target}{Variant}TestSuite (por exemplo, ./gradlew updateScreenshotTestDefaultDemoDebugTestSuite)
• Windows: gradlew updateScreenshotTestDefaultDemoDebugTestSuite

As imagens de referência são geradas e salvas em:

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

2. Verificar e executar testes

Renderizar capturas de tela novas e compará-las com imagens de referência:

• Linux e macOS: ./gradlew test{SuiteName}{Target}{Variant}TestSuite (por exemplo, ./gradlew testScreenshotTestDefaultDemoDebugTestSuite)
• Windows: gradlew testScreenshotTestDefaultDemoDebugTestSuite

Inspecionar relatórios de teste

Se forem detectadas diferenças ou se os testes falharem, o AGP vai gerar um relatório de teste em HTML.

• Local do relatório: {module}/build/reports/tests/{taskName}/index.html (por exemplo, app/build/reports/tests/testScreenshotTestDefaultDemoDebugTestSuite/index.html)

O relatório atualizado inclui:

• Card de metadados do cabeçalho: mostra o nome do teste, o método de prévia, a variante, o conjunto e o selo de status.
• Categorização de erros: sinaliza claramente Reference Image Missing, Image Size Mismatch ou Pixel Mismatch com rastreamentos de pilha copiáveis.
• Diferença visual dinâmica: destaca modificações sutis com intensidade menor e mudanças importantes com ênfase de alto contraste para evitar a absorção de elementos aninhados.

Migrar do plug-in independente legado

Para migrar do plug-in independente legado de captura de tela para os conjuntos de testes do AGP, atualize a configuração do Gradle e os comandos de tarefa.

Comparação de DSL de configuração do build

Plug-in independente legado (descontinuado)

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

Pacotes de teste do AGP (recomendado)

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

Mapeamento de tarefas e caminhos