Os pacotes de testes instrumentados empacotam testes de dispositivo em APKs
testApk isolados fora do diretório src/androidTest/ padrão
do módulo. Configure-os com a DSL de pacotes de testes do Plug-in do Android para Gradle (AGP) para separar as verificações de interface, integração ou de ponta a ponta com dependências, variantes e segmentações por dispositivo dedicadas.
Requisitos
Para usar pacotes de testes de instrumentação, 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 - Um dispositivo ou emulador conectado pelo Android Debug Bridge (adb) ou uma definição de dispositivo gerenciado pelo build.
Para mais informações sobre a correspondência de versões de pré-lançamento, consulte Compatibilidade com as prévias do Plug-in do Android para Gradle.
Configurar um pacote de testes instrumentados
Para adicionar um pacote de testes de instrumentação a um módulo de app ou biblioteca, siga estas etapas:
Ativar pacotes de testes
No arquivo gradle.properties do projeto, ative o suporte ao pacote de testes:
android.experimental.testSuiteSupport=true
Configurar o pacote
No arquivo build.gradle.kts do módulo, crie um pacote dentro do bloco
testOptions.customSuites com os blocos testApk e
useJunitEngine e os valores de tipo enumerado
AgpTestSuiteInputParameters:
import com.android.build.api.dsl.AgpTestSuiteInputParameters
android {
testOptions {
// Optional: define build-managed virtual devices and device groups.
managedDevices {
localDevices {
create("api34Atd") {
// Use a device profile from Android Studio.
device = "Pixel 6"
apiLevel = 34
systemImageSource = "aosp-atd"
}
}
groups {
create("ciPhones") {
targetDevices.add(allDevices.getByName("api34Atd"))
}
}
}
customSuites {
create("androidSuite") {
targetVariants += listOf("debug")
testApk {
dependencies {
implementation("junit:junit:4.13.2")
implementation("androidx.test.ext:junit:1.2.1")
implementation("androidx.test:runner:1.6.2")
}
}
useJunitEngine {
includeEngines += listOf("android-test-engine")
// Match the engine and listener versions to your AGP
// version.
enginesDependencies.add(
"com.android.tools.androidtest:" +
"android-test-engine:9.6.0-alpha03"
)
enginesDependencies.add(
"com.android.tools.androidtest:" +
"android-test-engine-result-listener:9.6.0-alpha03"
)
enginesDependencies.add(
"org.junit.platform:junit-platform-launcher:1.10.2"
)
inputs += listOf(
// Omit TESTED_APKS in com.android.library modules.
AgpTestSuiteInputParameters.TESTED_APKS,
AgpTestSuiteInputParameters.TEST_APKS,
AgpTestSuiteInputParameters.ADB_EXECUTABLE,
AgpTestSuiteInputParameters.AAPT2_EXECUTABLE,
)
}
targets {
// Runs on connected adb devices.
create("default")
// Optional: runs on build-managed devices or groups in
// targetDevices.
create("managed") {
targetDevices += listOf("ciPhones")
}
}
}
}
}
}
O AGP configura o executor de teste AndroidJUnitRunner e os IDs de pacote
automaticamente sem herdar dependências da
configuração androidTestImplementation. Para usar um executor personalizado, defina o
atributo android:name no elemento instrumentation no
arquivo src/{suiteName}/AndroidManifest.xml.
Criar testes
Coloque os testes de instrumentação no diretório {module}/src/{suiteName}/kotlin/ ou java/,
junto com os diretórios opcionais res/ ou assets/ ou um
arquivo AndroidManifest.xml. Por exemplo, crie o
arquivo app/src/androidSuite/kotlin/com/example/myapp/AppContextSuiteTest.kt:
package com.example.myapp
import androidx.test.ext.junit.runners.AndroidJUnit4
import androidx.test.platform.app.InstrumentationRegistry
import org.junit.Assert.assertEquals
import org.junit.Test
import org.junit.runner.RunWith
@RunWith(AndroidJUnit4::class)
class AppContextSuiteTest {
@Test
fun useAppContext() {
val appContext =
InstrumentationRegistry.getInstrumentation().targetContext
assertEquals("com.example.myapp", appContext.packageName)
}
}
Combinar testes de unidade e instrumentados
Para executar testes de JVM locais e testes de dispositivos instrumentados em uma única tarefa do Gradle,
declare os blocos hostJar e testApk em um único pacote. Coloque
os testes de host no diretório src/{suiteName}/test/ e os testes de dispositivo no
diretório src/{suiteName}/androidTest/:
import com.android.build.api.dsl.AgpTestSuiteInputParameters
android {
testOptions {
customSuites {
create("combinedSuite") {
targetVariants += listOf("debug")
hostJar {
dependencies {
implementation(
"org.junit.jupiter:junit-jupiter-api:5.10.2"
)
}
}
testApk {
dependencies {
implementation("junit:junit:4.13.2")
implementation("androidx.test.ext:junit:1.2.1")
implementation("androidx.test:runner:1.6.2")
}
}
useJunitEngine {
includeEngines += listOf(
"junit-jupiter",
"android-test-engine",
)
enginesDependencies.add(
"org.junit.jupiter:junit-jupiter-engine:5.10.2"
)
enginesDependencies.add(
"com.android.tools.androidtest:" +
"android-test-engine:9.6.0-alpha03"
)
enginesDependencies.add(
"com.android.tools.androidtest:" +
"android-test-engine-result-listener:9.6.0-alpha03"
)
enginesDependencies.add(
"org.junit.platform:junit-platform-launcher:1.10.2"
)
inputs += listOf(
// Omit TESTED_APKS in com.android.library modules.
AgpTestSuiteInputParameters.TESTED_APKS,
AgpTestSuiteInputParameters.TEST_APKS,
AgpTestSuiteInputParameters.ADB_EXECUTABLE,
AgpTestSuiteInputParameters.AAPT2_EXECUTABLE,
)
}
targets {
create("default")
}
}
}
}
}
Executar testes e coletar cobertura
Use o Gradle para executar pacotes instrumentados, filtrar casos de teste e gerar relatórios de cobertura.
Executar em dispositivos conectados ou gerenciados pelo build
Execute um destino conectado em todos os dispositivos adb on-line ou execute um destino configurado
com a propriedade targetDevices:
# Run on connected adb devices. ./gradlew :app:testDebugAndroidSuiteDefaultTestSuite# Run on the ciPhones build-managed device group. ./gradlew :app:testDebugAndroidSuiteManagedCiPhonesTestSuite
Filtrar testes de instrumentação
Filtre os testes com a opção --tests ou os argumentos AndroidJUnitRunner do Gradle:
./gradlew :app:testDebugAndroidSuiteDefaultTestSuite \
--tests "com.example.myapp.AppContextSuiteTest.useAppContext"Também é possível transmitir argumentos AndroidJUnitRunner na linha de comando com uma
propriedade de projeto, como
-Pandroid.testInstrumentationRunnerArguments.size=small. Para definir argumentos padrão do executor
no bloco useJunitEngine, chame o método addInputProperty,
como addInputProperty("android-test.instrumentation-args", "size=small").
Coletar cobertura de código no dispositivo
A cobertura de código no dispositivo requer um build depurável e um dispositivo com o Android 9 (nível 28 da API) ou mais recente. Para coletar a cobertura de um pacote instrumentado ou misto, siga estas etapas:
- Defina a propriedade
android.experimental.androidTest.coverage.useOnDeviceAgent=trueno arquivogradle.properties. - Defina a propriedade
codeCoveragecomotrueno pacote. - Se vários dispositivos estiverem conectados, use a variável de ambiente
ANDROID_SERIALpara segmentar um deles.
Para mais informações sobre os requisitos do agente, consulte Ver relatórios de cobertura de código (com o agente no dispositivo).
Inspecionar relatórios
Depois que uma execução de teste é concluída, o AGP gera saídas nos seguintes caminhos:
- Relatório de teste HTML:
{module}/build/reports/tests/{taskName}/index.html - Resultados XML do JUnit:
{module}/build/test-results/{taskName}/ - XML e logcat por dispositivo:
{module}/build/intermediates/{variant}/{taskName}/results/ - Relatório de cobertura de código:
{module}/build/reports/coverage/{suiteName}/index.html