مجموعه‌های آزمون در افزایه Android Gradle

افزایه Android Gradle‏ (AGP) به شما امکان می‌دهد آزمایش‌ها را در مجموعه آزمون‌های نام‌گذاری‌شده در بلوک testOptions واحدتان سازمان‌دهی کنید. هر مجموعه، مجموعه‌های منبع، وابستگی‌ها، موتورهای آزمایشی پلاتفرم JUnit، و تنوع‌های ساخت هدف خودش را تعریف می‌کند.

چرا باید از مجموعه آزمون استفاده کرد

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

  • آزمایش‌ها را براساس هدف جدا کنید: آزمایش‌های واحد، Robolectric، میانای کاربر، نماگرفت، و پشتیبان‌گیری را در دایرکتوری‌های اختصاصی src/{suiteName}/ نگه دارید و آن‌ها را در دایرکتوری‌های src/test/ یا src/androidTest/ باهم مخلوط نکنید.
  • جداسازی وابستگی‌ها و موتورها: مسیر کلاس هر مجموعه و موتور آزمایش پلاتفرم JUnit را بدون افزودن وابستگی به برنامه یا پیکربندی‌های testImplementation و androidTestImplementation پیکربندی کنید.
  • هدف قرار دادن انواع و دستگاه‌های خاص: انواع ساخت و دستگاه‌ها را برای هر مجموعه انتخاب کنید تا بررسی‌های سریع به‌صورت محلی اجرا شوند و مجموعه‌های طولانی‌تر در ادغام مداوم اجرا شوند.

انواع سوئیت

AGP شامل مجموعه آزمون‌های داخلی برای گردش‌های کاری تخصصی و میانای AgpTestSuite برای مجموعه‌های سفارشی است. جدول زیر انواع مجموعه دردسترس را فهرست می‌کند:

نوع سوئیت محتوی DSL هدف
مجموعه‌های آزمون واحد testOptions.customSuites آزمایش‌های JUnit 5،‏ JUnit 4، یا Robolectric را در JVM محلی با بلوک hostJar اجرا کنید.
مجموعه آزمون ابزاردار testOptions.customSuites آزمایش‌های دستگاه را در دستگاه‌های متصل یا تحت مدیریت ساخت با بلوک testApk و موتور آزمایش android-test-engine اجرا کنید.
آزمایش نماگرفت با مجموعه آزمون testOptions.screenshotTests پیش‌نماهای Compose @PreviewTest را در میزبان رندر و مقایسه کنید.
آزمایش بازیابی و پشتیبان‌گیری خودکار testOptions.backupTests داده‌های برنامه را در سراسر انتقال‌های محلی، ابری، و دستگاه‌به‌دستگاه تأیید کنید.
Journeys for Android Studio testOptions.customSuites مسیرهای کاربر XML مبتنی بر هوش مصنوعی را در دستگاه‌های متصل اجرا کنید.
دارایی سفارشی یا مجموعه‌های ترکیبی testOptions.customSuites تعاریف آزمایش ایستا را با موتور سفارشی اجرا کنید یا بلوک‌های hostJar، testApk، و assets را در یک مجموعه ترکیب کنید.

الزامات

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

  • استودیو Android نسخه Rabbit 3 Canary 3 یا بالاتر
  • AGP نسخه 9.6.0-alpha03 یا بالاتر
  • ‫Gradle نسخه ۹.۷.۱ یا بالاتر و JDK نسخه ۱۷ یا بالاتر
  • واحد com.android.application یا com.android.library

مجموعه‌های آزمون در ماژول‌های com.android.kotlin.multiplatform.library یا com.android.test پشتیبانی نمی‌شوند. برای اطلاعات بیشتر درباره مطابقت نسخه پیش‌نمایش، سازگاری با پیش‌نمایش‌های افزایه Android Gradle را ببینید.

راه‌اندازی مجموعه آزمون سفارشی

برای راهنمای راه‌اندازی گام‌به‌گام، مجموعه‌های آزمون واحد و مجموعه‌های آزمون ابزاری را ببینید. برای تعریف مجموعه سفارشی خودتان، ابتدا مجموعه‌های آزمون را در فایل gradle.properties پروژه‌تان فعال کنید:

android.experimental.testSuiteSupport=true

سپس، مجموعه‌ای را در بلوک testOptions.customSuites فایل build.gradle.kts واحدتان اعلام کنید. targetVariants ویژگی، یک یا چند بلوک منبع، useJunitEngine بلوک، و حداقل یک هدف در بلوک targets را مشخص کنید:

import com.android.build.api.dsl.AgpTestSuiteInputParameters

android {
    testOptions {
        customSuites {
            create("mySuite") {
                // Exact variant names to test, such as "debug" or "demoDebug".
                targetVariants += listOf("debug")

                // Add one or more blocks: hostJar {}, testApk {}, or assets {}.
                assets {}

                useJunitEngine {
                    includeEngines += listOf("my-custom-engine")
                    enginesDependencies.add(
                        "com.example:my-custom-junit-engine:1.0.0"
                    )
                    enginesDependencies.add(
                        "org.junit.platform:junit-platform-launcher:1.10.2"
                    )

                    // Request build and SDK artifacts read by your engine.
                    inputs += listOf(
                        AgpTestSuiteInputParameters.STATIC_FILES,
                        // Omit TESTED_APKS in com.android.library modules.
                        AgpTestSuiteInputParameters.TESTED_APKS,
                        AgpTestSuiteInputParameters.ADB_EXECUTABLE,
                    )
                }

                targets {
                    create("default")
                }
            }
        }
    }
}

در پیاده‌سازی سفارشی TestEngine، از ویژگی TestSuiteExecutionClient.default برای خواندن مقادیر شمارشی AgpTestSuiteInputParameters و ثابت‌های استاندارد TestEngineInputProperty مانند SERIAL_IDS و RESULTS_DIR استفاده کنید.

فهرست‌های راهنمای مجموعه منبع

چیدمان دایرکتوری هر مجموعه به این بستگی دارد که یک بلوک منبع را اعلام کند یا چندین بلوک منبع را ترکیب کند. جدول زیر مسیرهای پیش‌فرض را در فهرست راهنمای {module}/src/{suiteName}/ فهرست می‌کند:

بلوک منبع مجموعه تک‌منبعی مجموعه مختلط
hostJar kotlin/، java/، resources/ ‫test/kotlin/، test/java/، test/resources/
testApk ‫kotlin/،‏ java/،‏ res/،‏ assets/،‏ AndroidManifest.xml ‫androidTest/kotlin/،‏ androidTest/java/،‏ androidTest/res/،‏ androidTest/assets/،‏ androidTest/AndroidManifest.xml
assets دایرکتوری ریشه مجموعه assetsTest/

از نام‌های مجموعه منبع، طعم، نوع ساخت، یا گونه داخلی مانند main، androidTest، یا debug به‌عنوان نام مجموعه استفاده نکنید.

هدف‌های کنترل به‌ازای هر گونه

برای فعال یا غیرفعال کردن هدف مجموعه برای گونه‌های خاص، میانای TestSuiteTargetBuilder را ازطریق ویژگی HasTestSuitesBuilder.suites در بلوک beforeVariants پیکربندی کنید:

androidComponents {
    beforeVariants { variantBuilder ->
        if (variantBuilder.buildType == "release") {
            variantBuilder.suites["mySuite"]
                ?.targets
                ?.get("default")
                ?.enable = false
        }
    }
}

اجرای مجموعه‌ها و بازرسی گزارش‌ها

AGP برای هر ترکیب از گونه، مجموعه، و هدف یک تکلیف Gradle ایجاد می‌کند. جدول زیر الگوهای تکلیف را فهرست می‌کند:

نوع تکلیف الگوی نام‌گذاری فرمان نمونه
هدف مجموعه استاندارد test{Variant}{SuiteName}{Target}TestSuite ./gradlew :app:testDebugMySuiteDefaultTestSuite
هدف با خصوصیت targetDevices test{Variant}{SuiteName}{Target}{Devices}TestSuite ./gradlew :app:testDebugAndroidSuiteManagedCiPhonesTestSuite
به‌روزرسانی خط پایه (requiresUpdateTask = true) update{Variant}{SuiteName}{Target}TestSuite ./gradlew :app:updateDebugScreenshotTestDefaultTestSuite
تجمیع گزارش واحد testAllSuites ./gradlew :app:testAllSuites
انبوهش واحد و وابستگی testAllSuitesWithDependencies ./gradlew :app:testAllSuitesWithDependencies

تکالیف test، connectedCheck، و check مجموعه‌های سفارشی را اجرا نمی‌کنند مگراینکه آن‌ها را با روش withTestTaskProviders متصل کنید. برای فعال کردن تکالیف testAllSuites و testAllSuitesWithDependencies، ویژگی android.experimental.reportAggregationSupport=true را در فایل gradle.properties تنظیم کنید.

هر اجرای مجموعه، خروجی‌ها را در مکان‌های زیر می‌نویسد:

  • گزارش آزمایش HTML: {module}/build/reports/tests/{taskName}/index.html
  • نتایج JUnit XML: {module}/build/test-results/{taskName}/
  • گزارش پوشش کد: {module}/build/reports/coverage/{suiteName}/index.html
  • گزارش‌های انبوهشی: {module}/build/reports/{aggregationTask}/test-report/index.html و coverage-report/index.html

برای تولید گزارش‌های پوشش کد، ویژگی codeCoverage را روی true در مجموعه تنظیم کنید. برای مجموعه‌های نماگرفت Compose، مجموعه را در فایل build.gradle.kts با testOptions.customSuites.named("{suiteName}") { codeCoverage = true } پیکربندی کنید.

مشکلات و محدودیت‌های شناخته‌شده

مجموعه‌های آزمون محدودیت‌های زیر را دارند:

  • ادغام IDE: پشتیبانی «استودیو Android» از مجموعه‌های آزمون سفارشی دردسترس نیست. ویرایشگر کد ممکن است خطاهای مرجع حل‌نشده را در فایل‌های منبع مجموعه نشان دهد، حتی زمانی که ساخت شما به‌درستی پیکربندی شده باشد. درعوض، مجموعه آزمون‌ها را از خط فرمان بااستفاده از Gradle بسازید و اجرا کنید.
  • ذخیره کردن تکلیف در حافظه نهان: تکالیف مجموعه آزمون همیشه هنگام فراخوانی مجدداً اجرا می‌شوند و از حافظه نهان ساخت Gradle بار نمی‌شوند. مجموعه‌های بدون فایل آزمایشی با وضعیت NO-SOURCE رد می‌شوند.