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

החל מגרסה ‎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.

דרישות

כדי להשתמש ב-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 של הפרויקט ברמה הבסיסית (root), מפעילים את בדיקת צילומי המסך ואת התמיכה בחבילת מקרים לבדיקה:

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")
            }
        }
    }
}

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