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óriossrc/test/ousrc/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
testImplementationeandroidTestImplementation. - 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.applicationoucom.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.htmlecoverage-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.