يعد اختبار لقطات الشاشة طريقة فعالة للتحقق من كيفية ظهور واجهة المستخدم للمستخدمين. تجمع أداة "اختبار لقطات الشاشة من Compose Preview" بين بساطة وميزات المعاينات القابلة للإنشاء ومكاسب الإنتاجية الناتجة عن إجراء اختبارات لقطات الشاشة من جهة المضيف. إنشاء معاينة
اختبار لقطات الشاشة هو اختبار تلقائي يأخذ لقطة شاشة لجزء من واجهة المستخدم ثم يقارنه بصورة مرجعية تمّت الموافقة عليها سابقًا. في حال عدم تطابق الصور، فشل الاختبار ويعرض تقرير HTML لمساعدتك في مقارنة الاختلافات والعثور عليها.
باستخدام أداة اختبار لقطات الشاشة الخاصة بمعاينة Compose، يمكنك إجراء ما يلي:
- حدِّد عددًا من المعاينات الحالية أو الجديدة القابلة للإنشاء التي تريد استخدامها في اختبارات لقطات الشاشة.
- إنشاء صور مرجعية من تلك المعاينات القابلة للإنشاء
- يمكنك إنشاء تقرير HTML يحدِّد التغييرات على تلك المعاينات بعد إجراء تغييرات في الرمز.
- استخدِم مَعلمات
@Preview
، مثلuiMode
أوfontScale
، والمعاينات المتعدّدة لمساعدتك في توسيع نطاق الاختبارات. - يمكنك تخصيص الاختبارات باستخدام مجموعة المصادر الجديدة من "
screenshotTest
".
الشروط
لاستخدام اختبار لقطات الشاشة الخاصة بمعاينة Compose، تحتاج إلى ما يلي:
- إصدار Android Gradle 8.5.0-beta01 أو الإصدارات الأحدث
- Kotlin 1.9.20 أو إصدار أحدث.
ضبط إعدادات الجهاز
لتمكين الأداة، يُرجى اتباع الخطوات التالية:
- ثبِّت المكوّن الإضافي
com.android.compose.screenshot
، الإصدار0.0.1-alpha01
إلى مشروعك. - أضِف المكوّن الإضافي إلى ملف كتالوجات الإصدارات:
[versions] agp = "8.5.0-beta01" kotlin = "1.9.20" ... screenshot = "0.0.1-alpha01" [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
والتأكد من ضبطkotlinCompilerExtensionVersion
على 1.5.4 أو إصدار أحدث.android { ... composeOptions { kotlinCompilerExtensionVersion = "1.5.4" } experimentalProperties["android.experimental.enableScreenshotTest"] = true }
- تأكَّد من إضافة الاعتمادية
ui-tooling
.- يمكنك إضافته إلى كتالوجات الإصدارات:
[libraries] androidx-compose-ui-tooling = { group = "androidx.compose.ui", name = "ui-tooling"}
- أضِفه إلى ملف
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
.
المشاكل المعروفة
- إذا شاركت معاينة في مجموعة المصدر
screenshotTest
اسم الطريقة المؤهّلة بالكامل مع معاينة فيmain
، يتم استخدام المعاينة بشكل رئيسي بشكل غير صحيح للاختبار بدلاً من اختبار لقطة الشاشة.