Pacotes de testes instrumentados

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.application ou com.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:

  1. Defina a propriedade android.experimental.androidTest.coverage.useOnDeviceAgent=true no arquivo gradle.properties.
  2. Defina a propriedade codeCoverage como true no pacote.
  3. Se vários dispositivos estiverem conectados, use a variável de ambiente ANDROID_SERIAL para 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