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

בדיקת צילומי מסך היא דרך יעילה לאמת איך ממשק המשתמש נראה למשתמשים. הכלי לבדיקת צילומי מסך של תצוגות מקדימות ב-Compose משלב את הפשטות והתכונות של תצוגות מקדימות שניתן ליצור עם העלייה ביעילות שמתקבלת מהרצת בדיקות של צילומי מסך בצד המארח. הכלי ליצירה של תצוגות מקדימות של צילומי מסך נועד להיות קל לשימוש כמו הכלי ליצירה של תצוגות מקדימות.

בדיקת צילום מסך היא בדיקה אוטומטית שבה מתבצע צילום מסך של קטע בממשק המשתמש, ולאחר מכן מתבצעת השוואה לתמונה קודמת שאושרה. אם התמונות לא תואמות, הבדיקה נכשלת וייוצר דוח HTML שיעזור לכם להשוות ולמצוא את ההבדלים.

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

• מזהים מספר תצוגות מקדימות קיימות או חדשות שאפשר ליצור מהן קומפוזיציות, שרוצים להשתמש בהן לבדיקות של צילומי המסך.
• יצירת תמונות לדוגמה מהתצוגות המקדימות הניתנות ליצירה.
• יצירת דוח HTML שמזהה שינויים בתצוגות המקדימות האלה אחרי ביצוע שינויים בקוד.
• השתמשו בפרמטרים של @Preview, כמו uiMode או fontScale, ובתצוגות מקדימות מרובות כדי לעזור לכם להתאים את הבדיקות לקנה מידה נרחב.
• יצירת מודולים לבדיקות באמצעות קבוצת המקור החדשה screenshotTest.

הדרישות

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

• Android Gradle מגרסה 8.5.0-beta01 ואילך.
• Kotlin מגרסה 1.9.20 ואילך.

הגדרה

כדי להפעיל את הכלי:

1. מוסיפים את הפלאגין com.android.compose.screenshot, בגרסה 0.0.1-alpha07, לפרויקט.
1. מוסיפים את הפלאגין לקובץ של קטלוג הגרסאות:

   [versions]
   agp = "8.5.0-beta01"
   kotlin = "1.9.20"
   ...
   screenshot = "0.0.1-alpha07"
   
   [plugins]
   ...
   screenshot = { id = "com.android.compose.screenshot", version.ref = "screenshot"}
   

2. בקובץ build.gradle.kts ברמת המודול, מוסיפים את הפלאגין בבלוק plugins {}:

   plugins {
       ...
       alias(libs.plugins.screenshot)
   }
   

2. מפעילים את המאפיין הניסיוני בקובץ gradle.properties של הפרויקט.

   android.experimental.enableScreenshotTest=true
   

3. בבלוק android {} בקובץ build.gradle.kts ברמת המודול, מפעילים את הדגל הניסיוני כדי להשתמש בקבוצת המקור screenshotTest ומוודאים שהערך של kotlinCompilerExtensionVersion מוגדר ל-1.5.4 ואילך.

   android {
       ...
       composeOptions {
           kotlinCompilerExtensionVersion = "1.5.4"
       }
       experimentalProperties["android.experimental.enableScreenshotTest"] = true
   }
   

4. חשוב לוודא שהוספתם את יחסי התלות של ui-tooling.
   1. מוסיפים אותו לקטלוגים של הגרסאות:

      [libraries]
      androidx-compose-ui-tooling = { group = "androidx.compose.ui", name = "ui-tooling"}
      

   2. מוסיפים אותו לקובץ build.gradle.kts ברמת המודול:

      dependencies {
        screenshotTestImplementation(libs.androidx.compose.ui.tooling)
      }
      

הקצאת תצוגות מקדימות שניתן לשלב לשימוש בבדיקות של צילומי מסך

כדי לציין את התצוגות המקדימות שאפשר ליצור מהן קומפוזיציות שרוצים להשתמש בהן לבדיקות של צילומי מסך, צריך להוסיף את התצוגות המקדימות לכיתה לבדיקה. קובץ הכיתה של הבדיקה חייב להיות ממוקם בקבוצת המקור החדשה screenshotTest, לדוגמה app/src/screenshotTest/kotlin/com/google/yourapp/ExamplePreviewScreenshots.kt ({module}/src/screenshotTest/{kotlin|java}/com/your/package).

אפשר להוסיף עוד רכיבים שניתנים לשילוב ו/או תצוגות מקדימות, כולל תצוגות מקדימות מרובות, בקובץ הזה או בקבצים אחרים שנוצרו באותו קבוצת מקורות.

package com.google.yourapp

import androidx.compose.runtime.Composable
import androidx.compose.ui.tooling.preview.Preview
import com.google.yourapp.ui.theme.MyApplicationTheme

class ExamplePreviewsScreenshots {

    @Preview(showBackground = true)
    @Composable
    fun GreetingPreview() {
        MyApplicationTheme {
            Greeting("Android!")
        }
    }
}

יצירת תמונות לדוגמה

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

• ב-Linux וב-macOS: ‏ ./gradlew updateDebugScreenshotTest (./gradlew {:module:}update{Variant}ScreenshotTest)
• Windows: ‏ gradlew updateDebugScreenshotTest (gradlew {:module:}update{Variant}ScreenshotTest)

בסיום המשימה, תמונות העזרה יהיו ב-app/src/debug/screenshotTest/reference‏({module}/src/{variant}/screenshotTest/reference).

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

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

• ב-Linux וב-macOS: ‏ ./gradlew validateDebugScreenshotTest (./gradlew {:module:}validate{Variant}ScreenshotTest)
• Windows: ‏ gradlew validateDebugScreenshotTest (gradlew {:module:}validate{Variant}ScreenshotTest)

משימה האימות יוצרת דוח HTML בכתובת {module}/build/reports/screenshotTest/preview/{variant}/index.html.

בעיות מוכרות

הרשימה העדכנית של הבעיות המוכרות מופיעה ברכיב המעקב אחר בעיות של הכלי. אפשר לדווח על בעיות ועל משוב נוסף דרך מעקב הבעיות.

עדכוני גרסה

נתוני הגרסה ושינויים בגרסאות שוטפות

0.0.1-alpha06

בגרסה הזו נוספו:

סף ההבדל בין תמונות: הגדרת הסף הגלובלית החדשה הזו תאפשר לכם לשלוט בצורה מדויקת יותר בהשוואות של צילומי המסך. כדי להגדיר, מעדכנים את build.gradle.kts של המודול:

android {
    ...
    testOptions {
        ...
        screenshotTests {
            imageDifferenceThreshold = 0.0001f // 0.01%
        }
    }
}

הסף הזה יחול על כל בדיקות צילומי המסך שמוגדרות במודול.

• תיקוני באגים: תוקנו כמה באגים ב-Compose Renderer והוספה תמיכה ב-Compose ריק
• שיפורי ביצועים: אלגוריתם ההשוואה בין תמונות עודכן כדי שיהיה מהיר יותר