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

يُعدّ اختبار لقطات الشاشة طريقة فعّالة للتحقّق من شكل واجهة المستخدم لدى المستخدمين. تجمع أداة "اختبار لقطات الشاشة لمعاينة Compose" بين بساطة و ميزات المعاينات القابلة للإنشاء، وبين مزايا زيادة الإنتاجية التي توفرها اختبارات لقطات الشاشة على الجهاز المضيف. تم تصميم اختبار لقطة شاشة معاينة 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 Panda 1 Canary أو إصدار أحدث
• الإصدار 9.0 أو إصدار أحدث من المكوّن الإضافي لنظام Gradle المتوافق مع Android (AGP)
• الإصدار 0.0.1-alpha15 أو إصدار أحدث من مكوّن "اختبار لقطات الشاشة لمعاينة Compose" الإضافي
• الإصدار 2.2.10 أو إصدار أحدث من Kotlin
• الإصدار 17 أو إصدار أحدث من JDK
• تفعيل Compose لمشروعك ننصحك بتفعيل Compose باستخدام المكوّن الإضافي Compose Compiler Gradle.

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

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

الإعداد

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

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-alpha15 إلى مشروعك.

   1. أضف المكوّن الإضافي إلى ملف كتالوجات الإصدارات الخاص بك:

      [versions]
      agp = "9.0.0-rc03"
      kotlin = "2.1.20"
      screenshot = "0.0.1-alpha15"
      
      [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!")
    }
}

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

بعد إعداد صف تجريبي، عليك إنشاء صور مرجعية لكل معاينة. تُستخدَم هذه الصور المرجعية لتحديد التغييرات لاحقًا، بعد إجراء تغييرات على الرمز. لإنشاء صور مرجعية لاختبارات لقطات الشاشة الخاصة بالمعاينة القابلة للإنشاء، اتّبِع التعليمات الواردة في هذا القسم بشأن دمج بيئة التطوير المتكاملة أو مهام 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 واختَر تشغيل "اختبارات لقطات الشاشة".

إذا تعذّر إجراء اختبار، انقر على اسم الاختبار في لوحة تشغيل. اختَر علامة التبويب لقطة شاشة لفحص الاختلاف في الصورة باستخدام عناصر التحكّم المدمجة في التكبير والتصغير.

باستخدام مهام 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.

تحديد المشاكل وحلّها

تُجري أداة "اختبار لقطات الشاشة لمعاينة Compose" اختبارات على الجهاز المضيف، ما قد يستهلك الكثير من الذاكرة. يمكنك زيادة الحد الأقصى لحجم الذاكرة المؤقتة لآلة JVM الخاصة بالاختبار من خلال إضافة السمة التالية إلى ملف gradle.properties:

android.compose.screenshot.maxHeapSize=4g

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

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

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

تعديلات الإصدار

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