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

O teste de captura de tela é uma maneira eficaz de verificar a aparência da interface 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. O teste de captura de tela da visualização do Compose foi projetado para ser tão simples de usar quanto as visualizações 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 falhará e produzirá um relatório HTML para ajudar você a comparar e encontrar as diferenças.

Com a ferramenta de teste de captura de tela da visualização do Compose, você pode:

  • Usar @PreviewTest para criar testes de captura de tela para visualizações combináveis novas ou atuais.
  • Gerar imagens de referência dessas visualizações combináveis.
  • Gerar um relatório HTML que identifique mudanças nessas visualizações depois que você fizer mudanças no código.
  • Usar parâmetros @Preview, como uiMode ou fontScale, e várias visualizações para ajudar a dimensionar os testes.
  • Modularizar os testes com o novo conjunto de origem screenshotTest.
Figura 1. Exemplo de relatório HTML.

Integração de IDE

Embora seja possível usar a ferramenta de teste de captura de tela da visualização do Compose executando as tarefas do Gradle subjacentes (updateScreenshotTest e validateScreenshotTest) manualmente, o Android Studio Otter 3 Feature Drop Canary 4 apresenta uma integração completa do ambiente de desenvolvimento integrado. Isso permite gerar imagens de referência, executar testes e analisar falhas de validação totalmente no ambiente de desenvolvimento integrado. Confira alguns dos principais recursos:

  • Ícones de gutter no editor. Agora é possível executar testes ou atualizar imagens de referência diretamente do código-fonte. Ícones de execução verdes aparecem no gutter ao lado de elementos combináveis e classes anotadas com @PreviewTest.
    • Executar testes de captura de tela. Execute testes especificamente para uma única função ou para uma classe inteira.
    • Adicionar ou atualizar imagens de referência. Acione o fluxo de atualização especificamente para o escopo selecionado.

  • Gerenciamento interativo de referências. A atualização de imagens de referência agora é mais segura e granular.
    • Nova caixa de diálogo de geração de imagens de referência. Em vez de executar uma tarefa em massa do Gradle, uma nova caixa de diálogo permite visualizar e selecionar exatamente quais visualizações gerar ou atualizar.
    • Variações de visualização. A caixa de diálogo lista todas as variações de visualização (como tema claro ou escuro ou dispositivos diferentes) individualmente, permitindo selecionar ou desmarcar itens específicos antes de gerar imagens.

  • Resultados de teste integrados e visualizador de diferenças. Confira os resultados sem sair do ambiente de desenvolvimento integrado.
    • Painel de execução unificado. Os resultados do teste de captura de tela aparecem na janela de ferramentas Run padrão. Os testes são agrupados por classe e função, com o status de aprovação ou falha claramente marcado.
    • Ferramenta de diferenças visuais. Quando um teste falha, a guia Screenshot permite comparar as imagens Reference, Actual e Diff lado a lado.
    • Atributos detalhados. Uma guia Attributes fornece metadados sobre testes com falha, incluindo porcentagem de correspondência, dimensões da imagem e a configuração de visualização específica usada (por exemplo, uiMode ou fontScale).

  • Escopo de teste flexível. Agora é possível executar testes de captura de tela com vários escopos diretamente da visualização do projeto. Clique com o botão direito do mouse em um módulo, diretório, arquivo ou classe para executar testes de captura de tela especificamente para essa seleção.

Requisitos

Para usar o teste de captura de tela da visualização do Compose pela integração completa do ambiente de desenvolvimento integrado, seu projeto precisa atender aos seguintes requisitos:

  • Android Studio Panda 1 Canary 4 ou mais recente.
  • Plug-in do Android para Gradle (AGP, na sigla em inglês) versão 9.0 ou mais recente.
  • Plug-in de teste de captura de tela da visualização do Compose versão 0.0.1-alpha14 ou mais recente.
  • Kotlin versão 2.2.10 ou mais recente.
  • JDK versão 17 ou mais recente.
  • Compose ativado para seu projeto. Recomendamos ativar o Compose usando o plug-in do Gradle do compilador do Compose.

Se você quiser usar apenas as tarefas do Gradle subjacentes sem a integração do ambiente de desenvolvimento integrado, os requisitos serão os seguintes:

  • Plug-in do Android para Gradle (AGP, na sigla em inglês) versão 8.5.0 ou mais recente.
  • Plug-in de teste de captura de tela da visualização do Compose versão 0.0.1-alpha14 ou mais recente.
  • Kotlin versão 1.9.20 ou mais recente. Recomendamos usar o Kotlin 2.0 ou mais recente para que você possa usar o plug-in do Gradle do compilador do Compose.
  • JDK versão 17 ou mais recente.
  • Compose ativado para seu projeto. Recomendamos ativar o Compose usando o plug-in do Gradle do compilador do Compose.

Configuração

Tanto a ferramenta integrada quanto as tarefas do Gradle subjacentes dependem do plug-in de teste de captura de tela da visualização do Compose. Para configurar o plug-in, siga estas etapas:

  1. Ative a propriedade experimental no arquivo gradle.properties do projeto.

    android.experimental.enableScreenshotTest=true

  2. 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
}

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

    1. Adicione o plug-in ao arquivo de catálogos de versão:

      [versions]
agp = "9.0.0-rc03"
kotlin = "2.1.20"
screenshot = "0.0.1-alpha14"

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

    2. No arquivo build.gradle.kts no nível do módulo, adicione o plug-in no bloco plugins {}:

      plugins {
    alias(libs.plugins.screenshot)
}

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

    1. Adicione-as aos catálogos de versão:

      [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. 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 visualizações combináveis para usar em testes de captura de tela

Para designar as visualizações combináveis que você quer usar para testes de captura de tela, marque as visualizações com a anotação @PreviewTest. As visualizações precisam estar no novo conjunto de origem screenshotTest, por exemplo:

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

É possível adicionar mais elementos combináveis ou visualizações, incluindo várias visualizações, nesse arquivo ou em outros arquivos 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, é necessário gerar imagens de referência para cada visualização. Essas imagens de referência são usadas para identificar mudanças mais tarde, depois que você fizer mudanças no código. Para gerar imagens de referência para os testes de captura de tela da visualização combinável, siga as instruções nesta seção para a integração do ambiente de desenvolvimento integrado ou para as tarefas do Gradle.

No ambiente de desenvolvimento integrado

Clique no ícone de gutter ao lado de uma função @PreviewTest e selecione Add/Update Reference Images. Selecione as visualizações na caixa de diálogo e clique em Add.

Com as tarefas do Gradle

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, gere um relatório de teste seguindo as instruções nesta seção para a integração do ambiente de desenvolvimento integrado ou para as tarefas do Gradle.

No ambiente de desenvolvimento integrado

Clique no ícone de gutter ao lado de uma função @PreviewTest e selecione Run 'ScreenshotTests'.

Se um teste falhar, clique no nome do teste no painel Run. Selecione a guia Screenshot para inspecionar a diferença da imagem usando os controles integrados de zoom e panorâmica.

Com as tarefas do Gradle

Execute a tarefa de validação para fazer uma nova captura de tela e compará-la 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

  • Kotlin Multiplatform (KMP) : o ambiente de desenvolvimento integrado e o plug-in subjacente são projetados exclusivamente para projetos Android. Eles não oferecem suporte a destinos não Android em projetos KMP.

Você pode encontrar a lista completa de problemas conhecidos atuais no componente do Issue Tracker da ferramenta. Informe outros feedbacks e problemas pelo Issue Tracker.

Atualizações de versão

Para uma lista completa de atualizações de versão, consulte as notas de lançamento.