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

קל לארגן דפים בעזרת אוספים אפשר לשמור ולסווג תוכן על סמך ההעדפות שלך.

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

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

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

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

דרישות

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

• Android Gradle plugin מגרסה 8.5.0-beta01 ואילך.
• Kotlin מגרסה 1.9.20 ואילך. מומלץ להשתמש ב-Kotlin בגרסה 2.0 ואילך כדי שתוכלו להשתמש בפלאגין Gradle של Compose Compiler.

• Compose מופעל בפרויקט. מומלץ להפעיל את Compose באמצעות הפלאגין Compose Compiler Gradle.

הגדרה

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

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

   [versions]
   agp = "8.11.0-alpha06"
   kotlin = "2.1.20"
   screenshot = "0.0.1-alpha10"
   
   [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.

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

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

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

כדי לציין את התצוגות המקדימה שאפשר לשלב ולהשתמש בהן לבדיקות של צילומי מסך, מסמנים את התצוגות המקדימה באמצעות ההערה @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!")
    }
}

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

אחרי שמגדירים כיתה לבדיקה, צריך ליצור תמונות לדוגמה לכל תצוגה מקדימה. התמונות האלה משמשות לזיהוי שינויים מאוחר יותר, אחרי שמשנים את הקוד. כדי ליצור תמונות עזר לבדיקות של צילומי המסך בתצוגה המקדימה שאפשר לשלב, מריצים את המשימה הבאה ב-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).

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

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

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

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

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

• ספריית קובץ האימג' של העזרה השתנתה מ-{module}/src/{variant}/screenshotTest/reference ל-{module}/src/screenshotTest{Variant}/reference. כך תוכלו לוודא שהתמונות לדוגמה שנוצרות לא יהיו חלק מקוד הייצור, ותהיה התאמה למבנה הספרייה של סוגי בדיקות אחרים.

• המשימה {variant}PreviewScreenshotRender תוסר. עיבוד התמונות הועבר למנוע הבדיקה של JUnit.

• המשימה update{Variant}ScreenshotTest תבדוק את התמונות החדשות של הרינדור מול התמונות של ההפניה לפני העדכון. המערכת תעדכן רק תמונות שיש בהן הבדלים גדולים מסף מסוים. הדגל --updateFilter בשורת הפקודה הוסר.

0.0.1-alpha06

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

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

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

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

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