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

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

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

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

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

שילוב עם IDE

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

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

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

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

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

דרישות

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

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

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

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

הגדרה

גם הכלי המשולב וגם משימות 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)
}

הגדרת תצוגות מקדימות של קומפוננטות לשימוש בבדיקות צילומי מסך

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

ב-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 ובוחרים באפשרות הפעלה של 'ScreenshotTests'.

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

עם משימות 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.

פתרון בעיות

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

android.compose.screenshot.maxHeapSize=4g

בעיות מוכרות

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

הרשימה המלאה של הבעיות המוכרות הנוכחיות מופיעה ברכיב המעקב אחר בעיות בכלי. אפשר לדווח על משוב ובעיות אחרים באמצעות מעקב הבעיות.

עדכוני גרסה

רשימה מלאה של עדכוני הגרסה מופיעה בהערות המוצר.