الحزم الاختبارية في المكوّن الإضافي لنظام Gradle المتوافق مع Android

يتيح لك المكوّن الإضافي لنظام Gradle المتوافق مع Android (AGP) تنظيم الاختبارات في حِزم اختبارية مُسمّاة في مجموعة testOptions الخاصة بالوحدة. تحدّد كل حزمة مجموعات رموز المصدر والتبعيات ومحركات اختبار JUnit Platform وتنويعات التصميم المستهدَفة الخاصة بها.

مزايا استخدام الحزم الاختبارية

توفّر وحدة Android تلقائيًا مجموعة رموز مصدر واحدة test لاختبارات الوحدات المحلية ومجموعة رموز مصدر واحدة androidTest لاختبارات قياس حالة التطبيق. تفصل الحزم الاختبارية تنظيم الاختبار عن مجموعتَي رموز المصدر هاتين لكي تتمكّن من إجراء ما يلي:

  • فصل الاختبارات حسب الغرض منها: يجب الاحتفاظ باختبارات الوحدات وRobolectric وواجهة المستخدم ولقطات الشاشة والنسخ الاحتياطي في أدلة src/{suiteName}/ مخصّصة بدلاً من دمجها في أدلة src/test/ أو src/androidTest/.
  • عزل التبعيات والمحركات: يمكنك ضبط مسار فئة كل مجموعة ومحرك اختبار منصة JUnit بدون إضافة تبعيات إلى تطبيقك أو إعدادات testImplementation وandroidTestImplementation.
  • استهداف تنويعات وأجهزة معيّنة: يمكنك اختيار تنويعات التصميم والأجهزة لكل مجموعة اختبارات، بحيث يتم إجراء عمليات التحقّق السريعة محليًا وتشغيل المجموعات الأطول في عملية الدمج المتواصل.

أنواع الأجنحة

يتضمّن مكوّن AGP الإضافي حِزم اختبار مدمجة لسير العمل المتخصّص وواجهة AgpTestSuite للحِزم المخصّصة. يسرد الجدول التالي أنواع الحِزم المتاحة:

نوع الجناح حاوية DSL الغرض
حزم اختبارات الوحدات testOptions.customSuites يمكنك إجراء اختبارات JUnit 5 أو JUnit 4 أو Robolectric على جهاز Java الافتراضي (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 في حزمة واحدة.

المتطلبات

لاستخدام حِزم اختبارية مخصّصة، تأكَّد من أنّ مشروعك يستوفي المتطلبات التالية:

  • الإصدار Rabbit 3 Canary 3 من استوديو Android أو إصدار أحدث
  • الإصدار 9.6.0-alpha03 من "المكوّن الإضافي لنظام Gradle المتوافق مع Android" أو إصدار أحدث
  • الإصدار 9.7.1 من Gradle أو إصدار أحدث والإصدار 17 من JDK أو إصدار أحدث
  • وحدة com.android.application أو com.android.library

لا تتوفّر الحِزم الاختبارية في وحدات com.android.kotlin.multiplatform.library أو com.android.test. لمزيد من المعلومات حول مطابقة الإصدارات المبكرة الحصرية، يُرجى الاطّلاع على التوافق مع الإصدارات المبكرة الحصرية للمكوّن الإضافي لنظام Gradle المتوافق مع Android.

إعداد حزمة اختبارية مخصّصة

للحصول على أدلة إعداد مفصّلة، يُرجى الاطّلاع على حِزم اختبارات الوحدات وحِزم الاختبارات الآلية. لتحديد حزمة مخصّصة، فعِّل أولاً الحِزم الاختبارية في ملف 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
        }
    }
}

تشغيل المجموعات وفحص التقارير

ينشئ "المكوّن الإضافي لنظام Gradle المتوافق مع Android" مهمة Gradle لكل مجموعة من الصيغ والمجموعات والأهداف. يعرض الجدول التالي أنماط المهام:

نوع المهمة نمط التسمية مثال على طلب
هدف مجموعة الإعلانات العادية test{Variant}{SuiteName}{Target}TestSuite ./gradlew :app:testDebugMySuiteDefaultTestSuite
الاستهداف باستخدام السمة targetDevices test{Variant}{SuiteName}{Target}{Devices}TestSuite ./gradlew :app:testDebugAndroidSuiteManagedCiPhonesTestSuite
تحديث Baseline (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.