חבילות מקרים לבדיקה בפלאגין של Android Gradle

הפלאגין של Android Gradle‏ (AGP) מאפשר לארגן בדיקות בחבילות מקרים לבדיקה עם שמות בבלוק testOptions של המודול. כל חבילה מגדירה קבוצות מקורות, יחסי תלות, מנועי בדיקה של פלטפורמת JUnit ווריאנטים של גרסאות build משלה.

למה כדאי להשתמש בחבילות מקרים לבדיקה

כברירת מחדל, מודול של Android מספק קבוצת מקורות אחת מסוג test לבדיקות יחידה מקומיות וקבוצת מקורות אחת מסוג androidTest לבדיקות אינסטרומנטציה. חבילות מקרים לבדיקה מפרידות בין ארגון הבדיקות לבין שתי קבוצות המקורות האלה, כדי שתוכלו לבצע את הפעולות הבאות:

  • הפרדת בדיקות לפי מטרה: כדאי לשמור בדיקות של יחידות, Robolectric, ממשק משתמש, צילומי מסך וגיבוי בספריות src/{suiteName}/ ייעודיות, במקום לערבב אותן בספריות src/test/ או src/androidTest/.
  • בידוד של יחסי תלות ומנועים: מגדירים את ה-classpath של כל חבילה ואת מנוע הבדיקה של פלטפורמת JUnit בלי להוסיף יחסי תלות לאפליקציה או להגדרות של testImplementation ו-androidTestImplementation.
  • טירגוט של וריאנטים ומכשירים ספציפיים: בוחרים וריאנטים של build ומכשירים לכל חבילה, כדי שבדיקות מהירות יפעלו באופן מקומי וחבילות ארוכות יותר יפעלו בשילוב רציף.

סוגי הסוויטות

ה-AGP כולל חבילות מובנות של מקרים לבדיקה לתהליכי עבודה מיוחדים, ואת הממשק AgpTestSuite לחבילות מקרים לבדיקה בהתאמה אישית. בטבלה הבאה מפורטים סוגי החבילות הזמינים:

סוג הסוויטה מאגר DSL מטרה
חבילות מקרים לבדיקה של בדיקות יחידה testOptions.customSuites מריצים בדיקות של JUnit 5,‏ JUnit 4 או Robolectric ב-JVM המקומי באמצעות הבלוק hostJar.
חבילות מקרים לבדיקה עם כלים testOptions.customSuites מריצים בדיקות במכשירים מחוברים או במכשירים שמנוהלים ב-build באמצעות הבלוק testApk ומנוע הבדיקה android-test-engine.
בדיקת צילומי מסך באמצעות חבילות מקרים לבדיקה testOptions.screenshotTests עיבוד והשוואה של @PreviewTest תצוגות מקדימות של Compose במארח.
בדיקה אוטומטית של גיבוי ושחזור testOptions.backupTests אימות נתוני האפליקציה בהעברות מקומיות, בענן וממכשיר למכשיר.
‫Journeys ב-Android Studio testOptions.customSuites להריץ תהליכים מבוססי-AI שעוברים המשתמשים ב-XML במכשירים מחוברים.
נכסים בהתאמה אישית או חבילות מעורבות testOptions.customSuites אפשר להריץ הגדרות של בדיקות סטטיות עם מנוע מותאם אישית או לשלב את הבלוקים hostJar,‏ testApk ו-assets בחבילה אחת.

דרישות

כדי להשתמש בחבילות מקרים לבדיקה בהתאמה אישית, ודאו שהפרויקט עומד בדרישות הבאות:

  • ‫Android Studio Rabbit 3 Canary 3 ואילך
  • ‫AGP בגרסה 9.6.0-alpha03 ואילך
  • ‫Gradle מגרסה 9.7.1 ומעלה ו-JDK מגרסה 17 ומעלה
  • מודול com.android.application או com.android.library

חבילות מקרים לבדיקה לא נתמכות במודולים com.android.kotlin.multiplatform.library או com.android.test. מידע נוסף על התאמה של גרסאות טרום-השקה (Preview) זמין במאמר תאימות לגרסאות טרום-השקה (Preview) של הפלאגין של 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 כדי לקרוא ערכי enum של 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/

אל תשתמשו שוב בשמות של קבוצות מקורות, גרסאות, סוגי גרסאות build או וריאציות מובנים, כמו 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 Studio בחבילות מקרים לבדיקה בהתאמה אישית. יכול להיות שבעורך הקוד יוצגו שגיאות של הפניות לא פתורות בקובצי המקור של החבילה, גם אם ה-build מוגדר כמו שצריך. במקום זאת, אפשר ליצור ולהריץ חבילות של מקרים לבדיקה משורת הפקודה באמצעות Gradle.
  • שמירת משימות במטמון: משימות של חבילת מקרים לבדיקה תמיד מופעלות מחדש כשמפעילים אותן, והן לא נטענות מהמטמון של ה-build של Gradle. חבילות בלי קובצי בדיקה יקבלו את הסטטוס NO-SOURCE.