Pacotes de testes no Plug-in do Android para Gradle

O Plug-in do Android para Gradle (AGP) permite organizar testes em pacotes de testes nomeados no bloco testOptions do módulo. Cada pacote define os próprios conjuntos de origem, dependências, mecanismos de teste da plataforma JUnit e variantes de build de destino.

Por que usar pacotes de testes

Por padrão, um módulo do Android fornece um conjunto de origem test para testes de unidade locais e um conjunto de origem androidTest para testes de instrumentação. Os pacotes de testes desvinculam a organização de testes desses dois conjuntos de origem para que você possa fazer o seguinte:

  • Separe os testes por finalidade: mantenha os testes de unidade, do Robolectric, de interface, de captura de tela e de backup em diretórios src/{suiteName}/ dedicados, em vez de misturá-los nos diretórios src/test/ ou src/androidTest/.
  • Isolar dependências e mecanismos: configure o caminho de classe de cada pacote e o mecanismo de teste da plataforma JUnit sem adicionar dependências ao app ou às configurações testImplementation e androidTestImplementation.
  • Segmentar variantes e dispositivos específicos: selecione variantes de build e dispositivos por pacote para que as verificações rápidas sejam executadas localmente e os pacotes mais longos sejam executados na integração contínua.

Tipos de suíte

O AGP inclui pacotes de testes integrados para fluxos de trabalho especializados e a interface AgpTestSuite para pacotes personalizados. A tabela a seguir lista os tipos de pacote disponíveis:

Tipo de suíte Contêiner de DSL Finalidade
Pacotes de testes de unidade testOptions.customSuites Execute testes do JUnit 5, JUnit 4 ou Robolectric na JVM local com o bloco hostJar.
Pacotes de testes instrumentados testOptions.customSuites Execute testes de dispositivo em dispositivos conectados ou gerenciados pelo build com o bloco testApk e o mecanismo de teste android-test-engine.
Teste de captura de tela com pacotes de testes testOptions.screenshotTests Renderize e compare @PreviewTest prévias do Compose no host.
Teste automatizado de backup e restauração testOptions.backupTests Verifique os dados do app em transferências locais, na nuvem e de dispositivo para dispositivo.
Jornadas do Android Studio testOptions.customSuites Executar jornadas do usuário em XML com tecnologia de IA em dispositivos conectados.
Recurso personalizado ou pacotes mistos testOptions.customSuites Execute definições de teste estático com um mecanismo personalizado ou combine os blocos hostJar, testApk e assets em um pacote.

Requisitos

Para usar pacotes de testes personalizados, verifique se o projeto atende aos seguintes requisitos:

  • Android Studio Rabbit 3 Canary 3 ou mais recente
  • AGP 9.6.0-alpha03 ou mais recente
  • Gradle 9.7.1 ou mais recente e JDK 17 ou mais recente
  • Um módulo com.android.application ou com.android.library

Os pacotes de testes não são compatíveis com os módulos com.android.kotlin.multiplatform.library ou com.android.test. Para mais informações sobre a correspondência de versões de pré-lançamento, consulte Compatibilidade com pré-lançamentos do Plug-in do Android para Gradle.

Configurar um pacote de testes personalizado

Para ver guias de configuração detalhados, consulte Pacotes de testes de unidade e Pacotes de testes instrumentados. Para definir seu próprio pacote personalizado, primeiro ative os pacotes de testes no arquivo gradle.properties do projeto:

android.experimental.testSuiteSupport=true

Em seguida, declare um pacote no bloco testOptions.customSuites do arquivo build.gradle.kts do módulo. Especifique a propriedade targetVariants, um ou mais blocos de origem, o bloco useJunitEngine e pelo menos um destino no bloco targets:

import com.android.build.api.dsl.AgpTestSuiteInputParameters

android {
    testOptions {
        customSuites {
            create("mySuite") {
                // Exact variant names to test, such as "debug" or "demoDebug".
                targetVariants += listOf("debug")

                // Add one or more blocks: hostJar {}, testApk {}, or assets {}.
                assets {}

                useJunitEngine {
                    includeEngines += listOf("my-custom-engine")
                    enginesDependencies.add(
                        "com.example:my-custom-junit-engine:1.0.0"
                    )
                    enginesDependencies.add(
                        "org.junit.platform:junit-platform-launcher:1.10.2"
                    )

                    // Request build and SDK artifacts read by your engine.
                    inputs += listOf(
                        AgpTestSuiteInputParameters.STATIC_FILES,
                        // Omit TESTED_APKS in com.android.library modules.
                        AgpTestSuiteInputParameters.TESTED_APKS,
                        AgpTestSuiteInputParameters.ADB_EXECUTABLE,
                    )
                }

                targets {
                    create("default")
                }
            }
        }
    }
}

Em uma implementação personalizada de TestEngine, use a propriedade TestSuiteExecutionClient.default para ler valores de tipo enumerado AgpTestSuiteInputParameters e constantes padrão TestEngineInputProperty, como SERIAL_IDS e RESULTS_DIR.

Diretórios de conjuntos de origem

O layout do diretório de cada pacote depende se ele declara um bloco de origem ou combina vários blocos de origem. A tabela a seguir lista os caminhos padrão no diretório {module}/src/{suiteName}/:

Bloco de origem Pacote de fonte única Suíte mista
hostJar kotlin/, java/, resources/ test/kotlin/, test/java/, test/resources/
testApk kotlin/, java/, res/, assets/, AndroidManifest.xml androidTest/kotlin/, androidTest/java/, androidTest/res/, androidTest/assets/, androidTest/AndroidManifest.xml
assets Diretório raiz do pacote assetsTest/

Não reutilize nomes de conjuntos de origem, variações, tipos de build ou variantes integrados, como main, androidTest ou debug, como nome de um pacote.

Metas de controle por variante

Para ativar ou desativar um destino de pacote para variantes específicas, configure a interface TestSuiteTargetBuilder usando a propriedade HasTestSuitesBuilder.suites no bloco beforeVariants:

androidComponents {
    beforeVariants { variantBuilder ->
        if (variantBuilder.buildType == "release") {
            variantBuilder.suites["mySuite"]
                ?.targets
                ?.get("default")
                ?.enable = false
        }
    }
}

Executar pacotes e inspecionar relatórios

O AGP cria uma tarefa do Gradle para cada combinação de variante, pacote e destino. A tabela a seguir lista os padrões de tarefa:

Tipo de tarefa Padrão de nomenclatura Exemplo de comando
Meta do pacote padrão test{Variant}{SuiteName}{Target}TestSuite ./gradlew :app:testDebugMySuiteDefaultTestSuite
Segmentar com a propriedade targetDevices test{Variant}{SuiteName}{Target}{Devices}TestSuite ./gradlew :app:testDebugAndroidSuiteManagedCiPhonesTestSuite
Atualização do valor de referência (requiresUpdateTask = true) update{Variant}{SuiteName}{Target}TestSuite ./gradlew :app:updateDebugScreenshotTestDefaultTestSuite
Agregação de relatórios de módulos testAllSuites ./gradlew :app:testAllSuites
Agregação de módulos e dependências testAllSuitesWithDependencies ./gradlew :app:testAllSuitesWithDependencies

As tarefas test, connectedCheck e check não executam pacotes personalizados, a menos que você os conecte com o método withTestTaskProviders. Para ativar as tarefas testAllSuites e testAllSuitesWithDependencies, defina a propriedade android.experimental.reportAggregationSupport=true no arquivo gradle.properties.

Cada execução do pacote grava saídas nos seguintes locais:

  • Relatório de teste HTML: {module}/build/reports/tests/{taskName}/index.html
  • Resultados XML do JUnit: {module}/build/test-results/{taskName}/
  • Relatório de cobertura de código: {module}/build/reports/coverage/{suiteName}/index.html
  • Relatórios agregados: {module}/build/reports/{aggregationTask}/test-report/index.html e coverage-report/index.html

Para gerar relatórios de cobertura de código, defina a propriedade codeCoverage como true no pacote. Para pacotes de captura de tela do Compose, configure o pacote no arquivo build.gradle.kts com testOptions.customSuites.named("{suiteName}") { codeCoverage = true }.

Limitações e problemas conhecidos

Os pacotes de testes têm as seguintes limitações:

  • Integração com o ambiente de desenvolvimento integrado: o suporte do Android Studio para pacotes de testes personalizados não está disponível. O editor de código pode mostrar erros de referência não resolvidos em arquivos de origem do pacote, mesmo quando o build está configurado corretamente. Em vez disso, crie e execute pacotes de testes na linha de comando usando o Gradle.
  • Armazenamento em cache de tarefas: as tarefas do pacote de testes sempre são executadas novamente quando invocadas e não são carregadas do cache de build do Gradle. Os pacotes sem arquivos de teste são ignorados com o status NO-SOURCE.