مجموعه‌های آزمون ابزارگری‌شده

مجموعه آزمون‌های ابزاری، آزمایش‌های دستگاه را در فایل‌های APK مجزای testApk خارج از دایرکتوری پیش‌فرض src/androidTest/ مدول شما بسته‌بندی می‌کنند. آن‌ها را با DSL مجموعه آزمون افزایه Android Gradle (AGP) پیکربندی کنید تا میانای کاربر، ادغام، یا بررسی‌های سرتاسری را با وابستگی‌ها، متغیرها، و هدف‌های دستگاه اختصاصی جدا کنید.

الزامات

برای استفاده از مجموعه‌های آزمون ابزاردار، مطمئن شوید پروژه‌تان الزامات زیر را برآورده می‌کند:

  • استودیو Android نسخه Rabbit 3 Canary 3 یا بالاتر
  • AGP نسخه 9.6.0-alpha03 یا بالاتر
  • ‫Gradle نسخه ۹.۷.۱ یا بالاتر و JDK نسخه ۱۷ یا بالاتر
  • واحد com.android.application یا com.android.library
  • دستگاه یا شبیه‌سازی که ازطریق «پل اشکال‌زدایی Android»‏ (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 به‌طور خودکار و بدون به‌ارث بردن وابستگی‌ها از پیکربندی androidTestImplementation، شناسه‌های بسته و اجراکننده آزمایش AndroidJUnitRunner را پیکربندی می‌کند. برای استفاده از اجراکننده سفارشی، مشخصه 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 Gradle یا آرگومان‌های AndroidJUnitRunner فیلتر کنید:

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

همچنین می‌توانید آرگومان‌های AndroidJUnitRunner را در خط فرمان با ویژگی پروژه مانند -Pandroid.testInstrumentationRunnerArguments.size=small ارسال کنید. برای تنظیم آرگومان‌های پیش‌فرض اجراکننده در بلوک useJunitEngine، روش addInputProperty را فراخوانی کنید، مانند addInputProperty("android-test.instrumentation-args", "size=small").

جمع‌آوری پوشش کد درون‌دستگاهی

پوشش کد درون‌دستگاهی به ساخت قابل‌اشکال‌زدایی و دستگاهی نیاز دارد که Android نسخه ۹ (سطح میانای برنامه‌سازی کاربردی ۲۸) یا بالاتر را اجرا کند. برای جمع‌آوری پوشش برای مجموعه ابزاردار یا مختلط، مراحل زیر را تکمیل کنید:

  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