Наборы инструментальных тестов

Наборы инструментальных тестов упаковывают тесты устройств в изолированные APK-файлы testApk за пределами каталога src/androidTest/, который используется в модуле по умолчанию. Настройте их с помощью DSL наборов тестов плагина Android Gradle (AGP), чтобы разделить проверки интерфейса, интеграции и сквозные проверки с помощью специальных зависимостей, вариантов и таргетинга на устройства.

Требования

Чтобы использовать наборы инструментальных тестов, убедитесь, что ваш проект соответствует следующим требованиям:

  • Android Studio Rabbit 3 Canary 3 или более поздней версии.
  • AGP 9.6.0-alpha03 или более поздней версии;
  • Gradle 9.7.1 или более поздней версии и JDK 17 или более поздней версии.
  • Модуль com.android.application или com.android.library
  • Устройство или эмулятор, подключенные через Android Debug Bridge (adb), или определение устройства, управляемого сборкой.

Подробнее о совместимости с предварительными версиями плагина Android Gradle…

Как настроить набор инструментальных тестов

Чтобы добавить набор инструментальных тестов в модуль приложения или библиотеки, выполните следующие действия:

Включить наборы тестов

В файле gradle.properties проекта включите поддержку набора тестов:

android.experimental.testSuiteSupport=true

Настройте набор

В файле build.gradle.kts модуля создайте набор в блоке testOptions.customSuites с блоками testApk и useJunitEngine и значениями перечисления 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 автоматически настраивает идентификаторы пакетов и исполнителя тестов AndroidJUnitRunner, не наследуя зависимости из конфигурации androidTestImplementation. Чтобы использовать собственный исполнитель, задайте атрибут android:name для элемента instrumentation в файле src/{suiteName}/AndroidManifest.xml.

Создание тестов

Поместите инструментальные тесты в каталог {module}/src/{suiteName}/kotlin/ или java/ вместе с необязательными каталогами res/ или assets/ или файлом AndroidManifest.xml. Например, создайте файл 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)
    }
}

Объединение модульных и инструментальных тестов

Чтобы запустить локальные тесты JVM и тесты инструментированных устройств в одной задаче Gradle, объявите блоки hostJar и testApk в одном наборе. Поместите тесты хоста в каталог src/{suiteName}/test/, а тесты устройства – в каталог 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")
                }
            }
        }
    }
}

Запуск тестов и сбор данных о покрытии

Используйте Gradle для запуска наборов инструментов, фильтрации тестовых случаев и создания отчетов о покрытии.

Запуск на подключенных или управляемых сборкой устройствах

Запустите подключенную цель на каждом онлайн-устройстве adb или запустите цель, настроенную со свойством targetDevices:

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

Фильтрация инструментальных тестов

Фильтруйте тесты с помощью параметра --tests или аргументов AndroidJUnitRunner в Gradle.

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

Вы также можете передать аргументы AndroidJUnitRunner в командной строке со свойством проекта, например -Pandroid.testInstrumentationRunnerArguments.size=small. Чтобы задать аргументы по умолчанию в блоке useJunitEngine, вызовите метод addInputProperty, например addInputProperty("android-test.instrumentation-args", "size=small").

Сбор данных о покрытии кода на устройстве

Для покрытия кода на устройстве требуется отладочная сборка и устройство с Android 9 (уровень API 28) или более поздней версии. Чтобы собрать данные о покрытии для инструментального или смешанного набора тестов, выполните следующие действия:

  1. Задайте свойство android.experimental.androidTest.coverage.useOnDeviceAgent=true в файле gradle.properties.
  2. Задайте для свойства codeCoverage значение true.
  3. Если подключено несколько устройств, выберите одно из них с помощью переменной среды ANDROID_SERIAL.

Подробнее о требованиях к агенту см. в разделе Просмотр отчетов о покрытии кода (с агентом на устройстве).

Проверка отчетов

После завершения тестового запуска AGP генерирует выходные данные по следующим путям:

  • Отчет о тестировании HTML: {module}/build/reports/tests/{taskName}/index.html
  • Результаты JUnit XML: {module}/build/test-results/{taskName}/
  • XML-файл и файл logcat для каждого устройства: {module}/build/intermediates/{variant}/{taskName}/results/
  • Отчет о покрытии кода: {module}/build/reports/coverage/{suiteName}/index.html