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

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

android skills add testing-setup

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

בעזרת הכלי Compose Preview Screenshot Testing, אתם יכולים:

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

שילוב עם IDE

אפשר להשתמש בכלי לבדיקת צילומי מסך של תצוגה מקדימה ב-Compose על ידי הפעלה ידנית של משימות Gradle הבסיסיות (updateScreenshotTest ו-validateScreenshotTest), אבל בגרסת Canary 4 של השקת התכונות ב-Android Studio Otter 3 יש שילוב מלא של IDE. כך אפשר ליצור תמונות רפרנס, להריץ בדיקות ולנתח כשלים באימות, והכול בתוך ה-IDE. הנה כמה מהתכונות העיקריות:

• סמלים בשוליים של העורך. עכשיו אפשר להריץ בדיקות או לעדכן תמונות רפרנס ישירות מקוד המקור. סמלי הפעלה ירוקים מופיעים בשוליים לצד פונקציות קומפוזביליות ומחלקות עם הערות @PreviewTest.
  • הרצת בדיקות של צילומי מסך להריץ בדיקות לפונקציה אחת או לכיתה שלמה.
  • מוסיפים או מעדכנים תמונות רפרנס. מפעילים את תהליך העדכון באופן ספציפי להיקף שנבחר.

• ניהול אינטראקטיבי של קובצי עזר. עכשיו אפשר לעדכן תמונות רפרנס בצורה בטוחה ומפורטת יותר.
  • תיבת דו-שיח חדשה ליצירת תמונת רפרנס. במקום להריץ משימת Gradle בכמות גדולה, תיבת דו-שיח חדשה מאפשרת לכם לראות ולבחור בדיוק אילו תצוגות מקדימות ליצור או לעדכן.
  • צפייה בתצוגה מקדימה של הווריאציות. בתיבת הדו-שיח מופיעות כל הווריאציות של התצוגה המקדימה (למשל, עיצוב בהיר או עיצוב כהה, או מכשירים שונים) בנפרד, כך שאתם יכולים לבחור או לבטל את הבחירה של פריטים ספציפיים לפני שאתם יוצרים תמונות שנוצרו על ידי AI.

• תוצאות בדיקה משולבות ומציג הבדלים. הצגת התוצאות בלי לצאת מה-IDE.
  • חלונית הרצה מאוחדת. תוצאות הבדיקה של צילומי המסך מופיעות בחלון הרגיל של הכלי Run. הבדיקות מקובצות לפי מחלקה ופונקציה, והסטטוס "עבר" או "נכשל" מסומן בבירור.
  • כלי להשוואה חזותית. אם הבדיקה נכשלת, בכרטיסייה Screenshot אפשר להשוות בין התמונות Reference,‏ Actual ו-Diff זו לצד זו.
  • מאפיינים מפורטים. בכרטיסייה Attributes מוצגים מטא-נתונים על הבדיקות שנכשלו, כולל אחוז ההתאמה, מידות התמונה וההגדרות לתצוגה מקדימה הספציפיות שבהן השתמשתם (לדוגמה, uiMode או fontScale).

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

דרישות

כדי להשתמש ב-Compose Preview Screenshot Testing דרך השילוב המלא של IDE, הפרויקט צריך לעמוד בדרישות הבאות:

• ‫Android Studio Panda 1 Canary 4 ואילך.
• ‫פלאגין של Android Gradle ‏ (AGP) בגרסה 9.0 ואילך.
• גרסה 0.0.1-alpha16 ואילך של הפלאגין Compose Preview Screenshot Testing.
• ‫Kotlin מגרסה 2.2.10 ואילך.
• ‫JDK מגרסה 17 ואילך.
• ‫Compose מופעל בפרויקט. מומלץ להפעיל את Compose באמצעות הפלאגין של Gradle ל-Compose Compiler.

אם אתם רוצים להשתמש רק במשימות הבסיסיות של Gradle בלי השילוב של IDE, אלה הדרישות:

• ‫פלאגין של Android Gradle ‏ (AGP) בגרסה 8.5.0 ואילך.
• גרסה 0.0.1-alpha16 ואילך של הפלאגין Compose Preview Screenshot Testing.
• ‫Kotlin מגרסה 1.9.20 ואילך. מומלץ להשתמש ב-Kotlin בגרסה 2.0 ומעלה כדי שתוכלו להשתמש בפלאגין Compose Compiler Gradle.
• ‫JDK מגרסה 17 ואילך.
• ‫Compose מופעל בפרויקט. מומלץ להפעיל את Compose באמצעות הפלאגין של Gradle ל-Compose Compiler.

הגדרה

גם הכלי המשולב וגם משימות Gradle הבסיסיות מסתמכים על הפלאגין Compose Preview Screenshot Testing. כדי להגדיר את התוסף, בצע את הפעולות הבאות:

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

   android.experimental.enableScreenshotTest=true
   

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

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

3. מוסיפים לפרויקט את הפלאגין com.android.compose.screenshot, גרסה 0.0.1-alpha16.

   1. מוסיפים את הפלאגין לקובץ קטלוגי הגרסאות:

      [versions]
      agp = "9.0.0-rc03"
      kotlin = "2.2.10"
      screenshot = "0.0.1-alpha16"
      
      [plugins]
      screenshot = { id = "com.android.compose.screenshot", version.ref = "screenshot"}
      

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

      plugins {
          alias(libs.plugins.screenshot)
      }
      

4. מוסיפים את יחסי התלות screenshot-validation-api ו-ui-tooling.

   1. מוסיפים אותם לקטלוגי הגרסאות:

      [libraries]
      screenshot-validation-api = { group = "com.android.tools.screenshot", name = "screenshot-validation-api", version.ref = "screenshot"}
      androidx-ui-tooling = { group = "androidx.compose.ui", name = "ui-tooling"}
      

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

      dependencies {
        screenshotTestImplementation(libs.screenshot.validation.api)
        screenshotTestImplementation(libs.androidx.ui.tooling)
      }
      

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

כדי להגדיר את התצוגות המקדימות של ה-composable שבהן רוצים להשתמש לבדיקות של צילומי מסך, מסמנים את התצוגות המקדימות באמצעות ההערה @PreviewTest. התצוגות המקדימות צריכות להיות בקבוצת המקורות החדשה screenshotTest, לדוגמה:

app/src/screenshotTest/kotlin/com/example/yourapp/ ExamplePreviewScreenshotTest.kt

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

package com.example.yourapp

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

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

יצירת תמונות רפרנס

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

android studio render-compose-preview

ב-IDE

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

באמצעות משימות Gradle

מריצים את המשימה הבאה ב-Gradle:

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

אחרי שהמשימה מסתיימת, מאתרים את תמונות הרפרנס ב-app/src/screenshotTestDebug/reference ({module}/src/screenshotTest{Variant}/reference).

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

אחרי שקיימות תמונות רפרנס, יוצרים דוח בדיקה לפי ההוראות בקטע הזה לשילוב עם סביבת פיתוח משולבת (IDE) או למשימות Gradle.

ב-IDE

לוחצים על סמל השוליים לצד פונקציית @PreviewTest ובוחרים באפשרות Run 'ScreenshotTests'‎.

אם בדיקה נכשלת, לוחצים על שם הבדיקה בחלונית Run. בוחרים בכרטיסייה Screenshot כדי לבדוק את ההבדלים בתמונה באמצעות פקדי הזום וההזזה המשולבים.

באמצעות משימות Gradle

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

• ב-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.

פתרון בעיות

בדיקת צילומי מסך של תצוגה מקדימה ב-Compose מריצה בדיקות בצד המארח, שיכולות לצרוך הרבה זיכרון. כדי להגדיל את הגודל המקסימלי של ה-heap ב-JVM לבדיקה, מוסיפים את המאפיין הבא לקובץ gradle.properties:

android.compose.screenshot.maxHeapSize=4g

בעיות מוכרות

• ‫Kotlin Multiplatform (KMP): גם סביבת הפיתוח המשולבת וגם הפלאגין הבסיסי מיועדים אך ורק לפרויקטים של Android. הם לא תומכים ביעדים שאינם Android בפרויקטים של KMP.

הרשימה המלאה של הבעיות המוכרות כרגע מופיעה ברכיב מעקב הבעיות של הכלי. אפשר לשלוח משוב ולדווח על בעיות אחרות באמצעות Issue Tracker.

עדכוני גרסה

לרשימה המלאה של עדכוני הגרסאות, קראו את נתוני הגרסה.