اختبار لقطة الشاشة لإنشاء معاينة

يُعدّ اختبار لقطات الشاشة طريقة فعّالة للتحقّق من شكل واجهة المستخدم لدى المستخدمين. تجمع أداة "اختبار لقطات الشاشة لمعاينة Compose" بين بساطة المعاينات القابلة للإنشاء وميزاتها، وبين مزايا زيادة الإنتاجية التي توفرها اختبارات لقطات الشاشة على الجهاز المضيف. تم تصميم هذه الأداة لتكون سهلة الاستخدام مثل المعاينات القابلة للإنشاء.

اختبار لقطة الشاشة هو اختبار آلي يأخذ لقطة شاشة لجزء من واجهة المستخدم ثم يقارنها بصورة مرجعية تمت الموافقة عليها سابقًا. إذا لم تتطابق الصور، سيفشل الاختبار وسيتم إنشاء تقرير HTML لمساعدتك في المقارنة بين الصور والعثور على الاختلافات.

باستخدام أداة "اختبار لقطات الشاشة لمعاينة Compose"، يمكنك:

استخدام @PreviewTest لإنشاء اختبارات لقطات الشاشة للمعاينات الحالية أو الجديدة القابلة للإنشاء.
إنشاء صور مرجعية من تلك المعاينات القابلة للإنشاء
إنشاء تقرير HTML يحدّد التغييرات التي تم إجراؤها على تلك المعاينات بعد إجراء تغييرات على الرمز
استخدام مَعلمات @Preview، مثل uiMode أو fontScale، ومعاينات تنسيقات متعددة لمساعدتك في توسيع نطاق اختباراتك.
تقسيم اختباراتك إلى وحدات باستخدام مجموعة رموز المصدر screenshotTest الجديدة.

دمج بيئة التطوير المتكاملة (IDE)

يمكنك استخدام أداة "اختبار لقطات الشاشة لمعاينة Compose" من خلال تنفيذ مهام Gradle الأساسية (updateScreenshotTest وvalidateScreenshotTest) يدويًا، ولكن يقدّم الإصدار 4 من Android Studio Otter 3 Feature Drop Canary عملية دمج كاملة في بيئة التطوير المتكاملة. يتيح لك ذلك إنشاء صور مرجعية وإجراء اختبارات وتحليل حالات أخطاء في التحقّق ضمن بيئة التطوير المتكاملة. في ما يلي بعض الميزات الرئيسية:

رموز في هامش المحرّر يمكنك الآن إجراء اختبارات أو تعديل الصور المرجعية مباشرةً من رمز المصدر. تظهر رموز التشغيل الخضراء في هامش التحرير بجانب العناصر المركبة والفئات التي تمّت إضافة التعليقات التوضيحية إليها باستخدام @PreviewTest.
- إجراء اختبارات لقطات الشاشة: يمكنك تنفيذ الاختبارات لدالة واحدة أو لفئة بأكملها
- إضافة صور مرجعية أو تعديلها يمكنك بدء مسار تحديث خاص للنطاق المحدّد.

إدارة المراجع التفاعلية: أصبح تعديل الصور المرجعية أكثر أمانًا ودقة.
- مربّع حوار جديد لإنشاء صور مرجعية بدلاً من تنفيذ مهمة Gradle مجمّعة، يتيح لك مربّع حوار جديد عرض المعاينات واختيار المعاينات التي تريد إنشاؤها أو تعديلها بالضبط.
- معاينة جميع الأشكال يسرد مربّع الحوار جميع أشكال المعاينة (مثل المظهر الفاتح أو الداكن أو الأجهزة المختلفة) بشكل فردي، ما يتيح لك وضع علامة في مربّع الاختيار بجانب عناصر معيّنة أو إزالة العلامة قبل إنشاء الصور.

نتائج الاختبارات المتكاملة وعارض الاختلافات يتيح لك عرض النتائج بدون مغادرة بيئة التطوير المتكاملة
- لوحة التشغيل الموحّدة تظهر نتائج اختبار لقطة الشاشة في نافذة الأداة العادية تشغيل. يتم تجميع الاختبارات حسب الفئة والدالة، مع وضع علامة واضحة على حالة النجاح أو الفشل.
- أداة مقارنة مرئية عند تعذُّر الاختبار، تتيح لك علامة التبويب لقطة شاشة مقارنة الصور المرجعية والفعلية والمختلفة جنبًا إلى جنب.
- السمات التفصيلية تقدّم علامة التبويب السمات بيانات وصفية عن الاختبارات التي تعذّر إجراؤها، بما في ذلك نسبة التطابق وأبعاد الصورة وإعدادات المعاينة المحدّدة المستخدَمة (مثل uiMode أو fontScale).

نطاق الاختبار المرن يمكنك الآن تنفيذ اختبارات لقطات الشاشة بنطاقات مختلفة مباشرةً من "عرض المشروع". انقر بزر الماوس الأيمن على وحدة أو دليل أو ملف أو فئة لتشغيل اختبارات لقطات الشاشة الخاصة بهذا العنصر المحدّد.

المتطلبات

لاستخدام أداة "اختبار لقطات الشاشة لمعاينة Compose" من خلال الدمج الكامل مع بيئة التطوير المتكاملة، يجب أن يتضمن مشروعك الإصدارات التالية:

الإصدار 4 أو إصدار أحدث من Android Studio Panda 1 Canary
الإصدار 9.0 أو إصدار أحدث من المكوّن الإضافي لنظام Gradle المتوافق مع Android
الإصدار 0.0.1-alpha14 أو إصدار أحدث من مكوّن "اختبار لقطات الشاشة لمعاينة Compose" الإضافي
الإصدار 2.2.10 من Kotlin أو إصدار أحدث
الإصدار 17 من JDK أو إصدار أحدث
تفعيل Compose لمشروعك ننصحك بتفعيل Compose باستخدام المكوّن الإضافي Compose Compiler Gradle.

إذا كنت تريد استخدام مهام Gradle الأساسية فقط بدون الدمج مع بيئة التطوير المتكاملة، إليك المتطلبات:

الإصدار 8.5.0 أو إصدار أحدث من المكوّن الإضافي لنظام Gradle المتوافق مع Android (AGP)
الإصدار 0.0.1-alpha14 أو إصدار أحدث من مكوّن "اختبار لقطات الشاشة لمعاينة Compose" الإضافي
الإصدار 1.9.20 من Kotlin أو إصدار أحدث ننصحك باستخدام الإصدار 2.0 من Kotlin أو إصدار أحدث حتى تتمكّن من استخدام المكوّن الإضافي Compose Compiler Gradle.
الإصدار 17 من JDK أو إصدار أحدث
تفعيل Compose لمشروعك ننصحك بتفعيل Compose باستخدام المكوّن الإضافي Compose Compiler Gradle.

ضبط إعدادات الميزة

تعتمد كل من الأداة المدمجة ومهام Gradle الأساسية على المكوّن الإضافي "اختبار لقطات الشاشة لمعاينة Compose". لإعداد المكوّن الإضافي، اتّبِع الخطوات التالية:

فعِّل السمة التجريبية في ملف gradle.properties الخاص بمشروعك.
```
android.experimental.enableScreenshotTest=true
```
في حزمة android {} من ملف build.gradle.kts على مستوى الوحدة، فعِّل العلامة التجريبية لاستخدام مجموعة رموز المصدر screenshotTest.
```
android {
    experimentalProperties["android.experimental.enableScreenshotTest"] = true
}
```
أضِف المكوّن الإضافي com.android.compose.screenshot، الإصدار 0.0.1-alpha14 إلى مشروعك.
1. أضف المكوّن الإضافي إلى ملف كتالوجات الإصدارات الخاص بك:
```
[versions]
agp = "9.0.0-rc03"
kotlin = "2.1.20"
screenshot = "0.0.1-alpha14"

[plugins]
screenshot = { id = "com.android.compose.screenshot", version.ref = "screenshot"}
```
2. في ملف build.gradle.kts على مستوى الوحدة، أضِف المكوّن الإضافي في الحزمة plugins {}:
```
plugins {
    alias(libs.plugins.screenshot)
}
```

أضِف الاعتماديتَين 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.

في بيئة التطوير المتكاملة

انقر على رمز الهامش بجانب دالة @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).

إنشاء تقرير اختبار

بعد توفّر الصور المرجعية، أنشئ تقرير اختبار باتّباع التعليمات الواردة في هذا القسم بشأن دمج بيئة التطوير المتكاملة أو مهام Gradle.

في بيئة التطوير المتكاملة

انقر على رمز الهامش بجانب دالة @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.

المشاكل المعروفة

‫Kotlin Multiplatform (KMP): تم تصميم كل من بيئة التطوير المتكاملة والمكوّن الإضافي الأساسي حصريًا لمشاريع Android. ولا تتوافق مع الأنظمة الأساسية غير Android في مشاريع KMP.

يمكنك العثور على القائمة الكاملة بالمشاكل المعروفة الحالية في مكوّن Issue Tracker. يمكنك الإبلاغ عن أي ملاحظات ومشاكل أخرى من خلال Issue Tracker.

التحديثات

للاطّلاع على القائمة الكاملة بالتعديلات التي تم إجراؤها على الإصدار، يُرجى الرجوع إلى ملاحظات الإصدار.

اختبار لقطة الشاشة لإنشاء معاينة تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

دمج بيئة التطوير المتكاملة (IDE)

المتطلبات

ضبط إعدادات الميزة

حدد معاينات قابلة للإنشاء لاستخدامها في اختبارات لقطات الشاشة

إنشاء صور مرجعية

في بيئة التطوير المتكاملة

باستخدام مهام Gradle

إنشاء تقرير اختبار

في بيئة التطوير المتكاملة

باستخدام مهام Gradle

المشاكل المعروفة

التحديثات

اختبار لقطة الشاشة لإنشاء معاينة