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 de visualização do Compose combina a simplicidade e os recursos das visualizações de composição 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 de composição.

android skills add testing-setup

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 forem iguais, o teste vai 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:

• Use @PreviewTest para criar testes de captura de tela para prévias de composição novas ou existentes.
• Gerar imagens de referência com base nessas prévias de composição.
• Gerar um relatório HTML que identifica mudanças nessas prévias depois que você faz alterações no código.
• Use parâmetros @Preview, como uiMode ou fontScale, e várias prévias para ajudar a escalonar os testes.
• Modularize seus testes com o novo conjunto de origem screenshotTest.

Integração de IDE

Embora seja possível usar a ferramenta de teste de captura de tela da prévia do Compose executando as tarefas do Gradle (updateScreenshotTest e validateScreenshotTest) manualmente, o Android Studio Otter 3 Feature Drop Canary 4 apresenta uma integração completa com o ambiente de desenvolvimento integrado. Isso permite gerar imagens de referência, executar testes e analisar falhas de validação inteiramente 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 na gutter ao lado de funções de composição 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 prévias gerar ou atualizar.
  • Visualizar variações. A caixa de diálogo lista todas as variações de prévia (como tema claro ou escuro ou dispositivos diferentes) individualmente, permitindo que você selecione ou limpe itens específicos antes de gerar imagens.

• Resultados de testes 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 padrão Run. Os testes são agrupados por classe e função, com o status de aprovação ou reprovação claramente marcado.
  • Ferramenta de comparação visual. Quando um teste falha, a guia Captura de tela permite comparar as imagens de Referência, Reais e de Diferença lado a lado.
  • Atributos detalhados. A guia Attributes fornece metadados sobre testes com falha, incluindo porcentagem de correspondência, dimensões da imagem e a configuração da Preview 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 na 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 de visualização do Compose com a 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) versão 9.0 ou mais recente.
• Versão 0.0.1-alpha16 ou mais recente do plug-in de teste de captura de tela da visualização do Compose.
• Kotlin versão 2.2.10 ou mais recente.
• 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.

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

• Plug-in do Android para Gradle (AGP) versão 8.5.0 ou mais recente.
• Versão 0.0.1-alpha16 ou mais recente do plug-in de teste de captura de tela da visualização do Compose.
• Kotlin versão 1.9.20 ou mais recente. Recomendamos o uso do Kotlin 2.0 ou versões mais recentes para que você possa usar o plug-in do Gradle do compilador do Compose.
• 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

Tanto a ferramenta integrada quanto as tarefas do Gradle 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 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-alpha16, ao seu projeto.

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

      [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. No arquivo build.gradle.kts do módulo, adicione o plug-in ao bloco plugins {}:

      plugins {
          alias(libs.plugins.screenshot)
      }
      

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

   1. Adicione-as 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"}
      

   2. Adicione-as ao arquivo build.gradle.kts do módulo:

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

Designar prévias de composição para uso em testes de captura de tela

Para designar as prévias de composição que você quer usar para testes de captura de tela, marque-as com a anotação @PreviewTest. As prévias precisam estar localizadas no novo conjunto de origem screenshotTest, por exemplo:

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

É possível adicionar mais elementos que podem ser compostos 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, você precisa 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 alterações no código. Para gerar imagens de referência para os testes de captura de tela da visualização de composição, siga as instruções nesta seção para a integração do ambiente de desenvolvimento integrado ou para as tarefas do Gradle.

android studio render-compose-preview

No ambiente de desenvolvimento integrado

Clique no ícone de gutter ao lado de uma função @PreviewTest e selecione Adicionar/Atualizar Imagens de Referência. Selecione as visualizações na caixa de diálogo e clique em Adicionar.

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 dele no painel Run. Selecione a guia Screenshot para inspecionar a diferença de imagem usando os controles integrados de zoom e movimento.

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.

Solução de problemas

O teste de captura de tela de visualização do Compose executa testes do lado do host, que podem consumir muita memória. É possível aumentar o tamanho máximo de heap para a JVM de teste adicionando a seguinte propriedade ao arquivo gradle.properties:

android.compose.screenshot.maxHeapSize=4g

Problemas conhecidos

• Kotlin Multiplatform (KMP): o ambiente de desenvolvimento integrado e o plug-in foram criados exclusivamente para projetos do Android. Eles não são compatíveis com destinos que não sejam do Android em projetos KMP.

A lista completa de problemas conhecidos está disponível no componente do Issue Tracker da ferramenta. Informe qualquer outro feedback e problema pelo Issue Tracker.

Atualizações de versão

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