בדיקת צילומי מסך באמצעות חבילות בדיקה

החל מגרסה ‎9.5.0-alpha03 של פלאגין של Android Gradle‏ (AGP) וממנוע בדיקת צילומי המסך של Compose Preview 0.0.1-alpha16, בדיקת צילומי המסך משולבת עם מסגרת חבילות הבדיקה המקורית של AGP.

הגישה הזו מחליפה את תוסף צילומי המסך העצמאי (com.android.compose.screenshot). מומלץ להשתמש בחבילות בדיקה של AGP מהסיבות הבאות:

• מחזור חיים מקורי של משימות Gradle: בדיקות צילומי המסך משולבות ישירות במחזורי החיים הרגילים של בדיקות Gradle ו-AGP, וכך משפרות את הבידוד של המשימות ואת מהימנות הביצוע של הבדיקות.
• תמיכה בחבילות מותאמות אישית ובחבילות עם כמה וריאנטים: אתם יכולים ליצור כמה חבילות נפרדות של בדיקות צילומי מסך (כמו screenshotTest, ‏ uiTests או smokeTests) במודול אחד, ולבחור וריאנטים ספציפיים של גרסאות build (כמו demoDebug או release), במקום להיות מוגבלים לקובץ מקור אחד שהוגדר מראש.
• ביצועי בנייה משופרים ובידוד: חבילות הבדיקה של AGP משתמשות בהמרות מובנות של ארטיפקטים (כמו חילוץ של זמן הריצה של Layoutlib) ובטעינת מחלקות מבודדת, עם תמיכה מלאה ב-Gradle Configuration Caching וב-Project Isolation.

android skills add testing-setup

דרישות

כדי להשתמש ב-Compose Screenshot Testing עם חבילות בדיקה, צריך לוודא שהסביבה עומדת בדרישות הבאות:

• ‫Android Studio Rabbit 1 Canary 4 ואילך.
• פלאגין של Android Gradle‏ (AGP) בגרסה ‎9.5.0-alpha03 ואילך.
• גרסה 0.0.1-alpha16 ומעלה של Compose Screenshot Engine.
• ‫JDK מגרסה 17 ואילך.
• האפשרות Compose מופעלת בפרויקט. מומלץ להפעיל את Compose באמצעות התוסף Compose Compiler Gradle.

הגדרות ותצורה

כדי להגדיר בדיקות צילומי מסך של Compose באמצעות חבילות בדיקה, מבצעים את השלבים הבאים:

‫1. הפעלת תכונות ניסיוניות

בקובץ gradle.properties של השורש בפרויקט, מפעילים את בדיקת צילומי המסך ואת התמיכה בחבילת מקרים לבדיקה:

android.experimental.enableScreenshotTest=true
android.experimental.testSuiteSupport=true

2. הגדרת חבילת מקרים לבדיקה בקובץ build.gradle.kts

בקובץ build.gradle.kts של המודול, מגדירים חבילת מקרים לבדיקה של צילומי מסך בתוך הבלוק testOptions:

android {
    testOptions {
        screenshotTests.create("screenshotTest") { // suiteName can be customized (for example, "uiTests")
            engineVersion = "0.0.1-alpha16"
            targetVariants.add("demoDebug") // Add specific variants to test

            dependencies {
                implementation(libs.androidx.compose.ui.tooling)
                implementation("com.android.tools.screenshot:screenshot-validation-api:0.0.1-alpha16")
            }
        }
    }
}

3. יצירת קבוצת מקורות לבדיקה

יוצרים ספרייה ייעודית של קבוצת מקורות שתואמת לשם החבילה:

{module}/src/{suiteName}/kotlin/

לדוגמה, אם החבילה נקראת screenshotTest:

feature/foryou/impl/src/screenshotTest/kotlin/com/example/app/ForYouScreenTest.kt

4. הגדרת בדיקות של תצוגה מקדימה של רכיבים קומפוזביליים

מוסיפים הערות ל-Composable עם @PreviewTest והערות רגילות @Preview או הערות של תצוגה מקדימה מרובה:

package com.example.app

import androidx.compose.runtime.Composable
import androidx.compose.ui.tooling.preview.Preview
import com.android.tools.screenshot.PreviewTest
import com.example.app.ui.theme.AppTheme

@PreviewTest
@Preview(showBackground = true)
@Composable
fun ForYouScreenPreview() {
    AppTheme {
        ForYouScreen(isSyncing = false)
    }
}

הרצת בדיקות של צילומי מסך

חבילות בדיקה של AGP יוצרות משימות Gradle ייעודיות על סמך שם החבילה, היעד והווריאנטים.

‫1. יצירה או עדכון של תמונות לדוגמה

רינדור של תצוגות מקדימות של רכיבים ואיחסון של תמונות הייחוס של קו הבסיס המוזהב:

• ‫Linux ו-macOS: ./gradlew update{SuiteName}{Target}{Variant}TestSuite (לדוגמה, ./gradlew updateScreenshotTestDefaultDemoDebugTestSuite)
• ‫Windows: gradlew updateScreenshotTestDefaultDemoDebugTestSuite

תמונות לדוגמה נוצרות ונשמרות במיקום הבא:

{module}/src/{suiteName}{Target}{Variant}/reference/

2. אימות והרצת בדיקות

הצגת צילומי מסך חדשים והשוואה שלהם לתמונות להשוואה:

• ‫Linux ו-macOS: ./gradlew test{SuiteName}{Target}{Variant}TestSuite (לדוגמה, ./gradlew testScreenshotTestDefaultDemoDebugTestSuite)
• ‫Windows: gradlew testScreenshotTestDefaultDemoDebugTestSuite

בדיקת דוחות בדיקה

אם המערכת מזהה הבדלים או שהבדיקות נכשלות, AGP יוצר דוח בדיקה ב-HTML.

• מיקום הדוח: {module}/build/reports/tests/{taskName}/index.html (לדוגמה, app/build/reports/tests/testScreenshotTestDefaultDemoDebugTestSuite/index.html)

הדוח המעודכן כולל:

• כרטיס מטא-נתונים של הכותרת: מוצגים בו שם הבדיקה, שיטת התצוגה המקדימה, הווריאציה, החבילה ותג הסטטוס.
• סיווג שגיאות: סימון ברור של שגיאות Reference Image Missing, Image Size Mismatch או Pixel Mismatch עם עקבות מחסנית שניתן להעתיק.
• השוואה חזותית דינמית: מדגישה שינויים קלים בעזרת עצימות נמוכה ושינויים משמעותיים בעזרת ניגודיות גבוהה, כדי למנוע מצב שבו רכיבים מוטמעים נעלמים.

מעבר מהפלאגין העצמאי מהדור הקודם

כדי לבצע מיגרציה מהפלאגין העצמאי לצילומי מסך מדור קודם לחבילות בדיקה של AGP, צריך לעדכן את הגדרות Gradle ואת פקודות המשימות.

השוואה בין DSL של הגדרות build

פלאגין עצמאי מדור קודם (יצא משימוש)

// In build.gradle.kts
plugins {
    alias(libs.plugins.screenshot)
}

dependencies {
    screenshotTestImplementation(libs.androidx.compose.ui.tooling)
    screenshotTestImplementation("com.android.tools.screenshot:screenshot-validation-api:0.0.1-alpha16")
}

חבילות בדיקה של AGP (מומלץ)

// In build.gradle.kts
android {
    testOptions {
        screenshotTests.create("screenshotTest") {
            engineVersion = "0.0.1-alpha16"
            targetVariants.add("demoDebug")

            dependencies {
                implementation(libs.androidx.compose.ui.tooling)
                implementation("com.android.tools.screenshot:screenshot-validation-api:0.0.1-alpha16")
            }
        }
    }
}

מיפוי של משימות ונתיבים