Esta página foi traduzida pela API Cloud Translation.

Teste de captura de tela da visualização do Compose

O teste de captura de tela é uma maneira eficaz de verificar como a interface aparece para os usuários. A ferramenta de teste de captura de tela da visualização do Compose combina a simplicidade e os recursos das visualizações combináveis com os ganhos de produtividade da execução de testes de captura de tela do lado do host. Teste de captura de tela da prévia do Compose O teste de captura de tela foi projetado para ser tão fácil de usar quanto as prévias combináveis.

Um teste de captura de tela é um teste automatizado que faz uma captura de tela de uma parte da interface e a compara com uma imagem de referência aprovada anteriormente. Se as imagens não corresponderem, o teste vai falhar e gerar um relatório HTML para ajudar você a comparar e encontrar as diferenças.

Com a ferramenta de teste de captura de tela da prévia do Compose, você pode:

Use @PreviewTest para criar testes de captura de tela para prévias combináveis novas ou atuais.
Gere imagens de referência com base nessas prévias combináveis.
Gere um relatório em HTML que identifique as mudanças nessas prévias depois de fazer alterações no código.
Use parâmetros @Preview, como uiMode ou fontScale, e várias prévias para ajudar a dimensionar seus testes.
Modularize seus testes com o novo conjunto de origem screenshotTest.

**Figura 1**. Exemplo de relatório HTML.

Requisitos

Para usar o teste de captura de tela da prévia do Compose, você precisa do seguinte:

Plug-in do Android para Gradle 8.5.0-beta01 ou mais recente.
Kotlin 1.9.20 ou mais recente. Recomendamos usar o Kotlin 2.0 ou versões mais recentes para poder usar o plug-in do Gradle do compilador do Compose.
JDK 23 ou versões anteriores. Essa ferramenta não é compatível com o JDK 24 ou versões mais recentes devido a uma dependência do Java Security Manager, que foi removido em versões mais recentes do JDK.
O Compose está ativado para seu projeto. Recomendamos ativar o Compose usando o plug-in do Gradle do compilador do Compose.

Observação: se não for possível usar o plug-in do Gradle do Compose Compiler, ative o Compose declarando uma dependência diretamente no Compose Compiler. Use a versão 1.5.4 ou mais recente do kotlinCompilerExtensionVersion.

Configurar

Para ativar a ferramenta, siga estas etapas:

Adicione o plug-in com.android.compose.screenshot, versão 0.0.1-alpha10 ao seu projeto.

Adicione o plug-in ao arquivo de catálogos de versões:

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

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

No arquivo build.gradle.kts do módulo, adicione o plug-in no bloco plugins {}:
```
plugins {
    alias(libs.plugins.screenshot)
}
```

Ative a propriedade experimental no arquivo gradle.properties do projeto.
```
android.experimental.enableScreenshotTest=true
```
No bloco android {} do arquivo build.gradle.kts no nível do módulo, ative a flag experimental para usar o conjunto de origem screenshotTest.
```
android {
    experimentalProperties["android.experimental.enableScreenshotTest"] = true
}
```

Adicione as dependências screenshot-validation-api e ui-tooling.

Adicione-os aos catálogos de versões:

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

Adicione-as ao arquivo build.gradle.kts no nível do módulo:

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

Designar prévias combináveis para usar em testes de captura de tela

Para designar as visualizações combináveis que você quer usar nos testes de captura de tela, marque as visualizações com a anotação @PreviewTest. As prévias precisam estar no novo conjunto de fontes screenshotTest, por exemplo, app/src/screenshotTest/kotlin/com/example/yourapp/ExamplePreviewScreenshotTest.kt.

É possível adicionar mais elementos combináveis e/ou prévias, incluindo várias prévias, neste arquivo ou em outros criados no mesmo conjunto de origem.

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

Gerar imagens de referência

Depois de configurar uma classe de teste, gere imagens de referência para cada prévia. Essas imagens de referência são usadas para identificar mudanças mais tarde, depois que você fizer alterações no código. Para gerar imagens de referência para seus testes de captura de tela de visualização combinável, execute a seguinte tarefa do Gradle:

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

Depois que a tarefa for concluída, encontre as imagens de referência em app/src/screenshotTestDebug/reference ({module}/src/screenshotTest{Variant}/reference).

Gerar um relatório de teste

Depois que as imagens de referência existirem, execute a tarefa de validação para fazer uma nova captura de tela e compare com a imagem de referência:

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

A tarefa de verificação cria um relatório HTML em {module}/build/reports/screenshotTest/preview/{variant}/index.html.

Problemas conhecidos

A lista atual de problemas conhecidos está no componente rastreador de problemas da ferramenta. Informe outros feedbacks e problemas pelo Issue Tracker.

Atualizações de versão

Notas da versão e mudanças para versões em andamento.

0.0.1-alpha10

Esta versão inclui:

A partir dessa versão, é necessário marcar todas as funções de prévia com a anotação @PreviewTest. As prévias sem a anotação não serão executadas.
O diretório de imagens de referência mudou de {module}/src/{variant}/screenshotTest/reference para {module}/src/screenshotTest{Variant}/reference. Isso garante que as imagens de referência geradas não façam parte do código de produção e estejam alinhadas com a estrutura de diretórios de outros tipos de teste.
A tarefa {variant}PreviewScreenshotRender é removida. A renderização de imagens é migrada para o mecanismo de teste do JUnit.
A tarefa update{Variant}ScreenshotTest compara novas imagens de renderização com imagens de referência antes de atualizar. Ele só atualiza imagens que têm diferenças maiores que um limite especificado. A flag de linha de comando --updateFilter foi removida.

0.0.1-alpha06