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

דרישות
כדי להשתמש בבדיקת צילומי מסך של טיוטות, צריך:
- פלאגין Android Gradle מגרסה 8.5.0-beta01 ואילך.
- Kotlin 1.9.20 ומעלה. מומלץ להשתמש ב-Kotlin בגרסה 2.0 ואילך כדי להשתמש בתוסף Compose Compiler Gradle.
- JDK 23 ומטה. הכלי הזה לא תואם ל-JDK 24 ומעלה בגלל תלות ב-Java Security Manager, שהוסר בגרסאות חדשות יותר של JDK
האפשרות Compose מופעלת בפרויקט. מומלץ להפעיל את Compose באמצעות התוסף Compose Compiler Gradle.
הגדרה
כדי להפעיל את הכלי, פועלים לפי השלבים הבאים:
- מוסיפים את הפלאגין
com.android.compose.screenshot
, גרסה0.0.1-alpha10
, לפרויקט. - מוסיפים את הפלאגין לקובץ קטלוג הגרסאות:
[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"}
- בקובץ
build.gradle.kts
ברמת המודול, מוסיפים את הפלאגין בבלוקplugins {}
:plugins { alias(libs.plugins.screenshot) }
- מפעילים את המאפיין הניסיוני בקובץ
gradle.properties
של הפרויקט.android.experimental.enableScreenshotTest=true
- בבלוק
android {}
בקובץbuild.gradle.kts
ברמת המודול, מפעילים את דגל הניסוי כדי להשתמש בערכת המקורscreenshotTest
.android { experimentalProperties["android.experimental.enableScreenshotTest"] = true }
- מוסיפים את יחסי התלות
screenshot-validation-api
ו-ui-tooling
.- מוסיפים אותם לקטלוגים של הגרסאות:
[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"}
- מוסיפים אותם לקובץ
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 Test Engine.במשימה
update{Variant}ScreenshotTest
, המערכת תשווה בין תמונות רינדור חדשות לבין תמונות הפניה לפני העדכון. הוא יעודכן רק אם יש הבדלים בתמונות שגדולים מסף מסוים. הוסר הדגל--updateFilter
בשורת הפקודה.
0.0.1-alpha06
בגרסה הזו הוספנו:
סף ההבדל בין תמונות: הגדרת הסף הגלובלית החדשה הזו תאפשר לכם לשלוט טוב יותר בהשוואות של צילומי מסך. כדי להגדיר, מעדכנים את הקובץ build.gradle.kts של המודול:
android {
testOptions {
screenshotTests {
imageDifferenceThreshold = 0.0001f // 0.01%
}
}
}
הסף הזה יחול על כל בדיקות צילומי המסך שמוגדרות במודול.
- תיקוני באגים: תיקנו כמה באגים ב-Compose Renderer והוספנו תמיכה בכתיבה ריקה
- שיפורים בביצועים: האלגוריתם להשוואת תמונות עודכן כדי לפעול מהר יותר