Suite pengujian berinstrumen

Suite pengujian berinstrumen mengemas pengujian perangkat ke dalam APK testApk yang terisolasi di luar direktori src/androidTest/ default modul Anda. Konfigurasikan dengan DSL suite pengujian plugin Android Gradle (AGP) untuk memisahkan UI, integrasi, atau pemeriksaan menyeluruh dengan dependensi, varian, dan penargetan perangkat khusus.

Persyaratan

Untuk menggunakan suite pengujian berinstrumen, pastikan project Anda memenuhi persyaratan berikut:

  • Android Studio Rabbit 3 Canary 3 atau yang lebih baru
  • AGP 9.6.0-alpha03 atau yang lebih tinggi
  • Gradle 9.7.1 atau yang lebih tinggi dan JDK 17 atau yang lebih tinggi
  • Modul com.android.application atau com.android.library
  • Perangkat atau emulator yang terhubung melalui Android Debug Bridge (adb) atau definisi perangkat yang dikelola build

Untuk mengetahui informasi selengkapnya tentang pencocokan versi pratinjau, lihat Kompatibilitas dengan pratinjau plugin Android Gradle.

Menyiapkan suite pengujian berinstrumen

Untuk menambahkan suite pengujian berinstrumen ke modul aplikasi atau library, selesaikan langkah-langkah berikut:

Mengaktifkan suite pengujian

Di file gradle.properties project Anda, aktifkan dukungan suite pengujian:

android.experimental.testSuiteSupport=true

Mengonfigurasi suite

Dalam file build.gradle.kts modul Anda, buat suite di dalam blok testOptions.customSuites dengan blok testApk dan useJunitEngine serta nilai enum 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")
                    }
                }
            }
        }
    }
}

AGP mengonfigurasi ID paket dan runner pengujian AndroidJUnitRunner secara otomatis tanpa mewarisi dependensi dari konfigurasi androidTestImplementation. Untuk menggunakan runner kustom, tetapkan atribut android:name pada elemen instrumentation di file src/{suiteName}/AndroidManifest.xml Anda.

Membuat pengujian

Tempatkan uji instrumentasi Anda di direktori {module}/src/{suiteName}/kotlin/ atau java/, bersama dengan direktori res/ atau assets/ opsional atau file AndroidManifest.xml. Misalnya, buat file 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)
    }
}

Menggabungkan pengujian unit dan uji instrumentasi

Untuk menjalankan pengujian JVM lokal dan pengujian perangkat berinstrumen dalam satu tugas Gradle, deklarasikan blok hostJar dan testApk dalam satu suite. Tempatkan pengujian host di direktori src/{suiteName}/test/ dan pengujian perangkat di direktori 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")
                }
            }
        }
    }
}

Menjalankan pengujian dan mengumpulkan cakupan

Gunakan Gradle untuk menjalankan suite berinstrumen, memfilter kasus pengujian, dan membuat laporan cakupan.

Menjalankan di perangkat yang terhubung atau dikelola build

Jalankan target yang terhubung di setiap perangkat adb online, atau jalankan target yang dikonfigurasi dengan properti targetDevices:

# Run on connected adb devices.
./gradlew :app:testDebugAndroidSuiteDefaultTestSuite
# Run on the ciPhones build-managed device group.
./gradlew :app:testDebugAndroidSuiteManagedCiPhonesTestSuite

Memfilter uji instrumentasi

Filter pengujian dengan opsi --tests atau argumen AndroidJUnitRunner Gradle:

./gradlew :app:testDebugAndroidSuiteDefaultTestSuite \
    --tests "com.example.myapp.AppContextSuiteTest.useAppContext"

Anda juga dapat meneruskan argumen AndroidJUnitRunner pada command line dengan properti project seperti -Pandroid.testInstrumentationRunnerArguments.size=small. Untuk menetapkan argumen runner default di blok useJunitEngine, panggil metode addInputProperty, seperti addInputProperty("android-test.instrumentation-args", "size=small").

Mengumpulkan cakupan kode di perangkat

Cakupan kode di perangkat memerlukan build yang dapat di-debug dan perangkat yang menjalankan Android 9 (level API 28) atau yang lebih tinggi. Untuk mengumpulkan cakupan suite yang diinstrumentasi atau campuran, selesaikan langkah-langkah berikut:

  1. Tetapkan properti android.experimental.androidTest.coverage.useOnDeviceAgent=true di file gradle.properties Anda.
  2. Tetapkan properti codeCoverage ke true di suite.
  3. Jika beberapa perangkat terhubung, targetkan satu perangkat dengan variabel lingkungan ANDROID_SERIAL.

Untuk mengetahui informasi selengkapnya tentang persyaratan agen, lihat Melihat laporan cakupan kode (dengan agen di perangkat).

Memeriksa laporan

Setelah uji coba selesai, AGP akan menghasilkan output di jalur berikut:

  • Laporan pengujian HTML: {module}/build/reports/tests/{taskName}/index.html
  • Hasil XML JUnit: {module}/build/test-results/{taskName}/
  • XML dan logcat per perangkat: {module}/build/intermediates/{variant}/{taskName}/results/
  • Laporan cakupan kode: {module}/build/reports/coverage/{suiteName}/index.html