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

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

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

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

باستخدام أداة "اختبار لقطات الشاشة" في ميزة "معاينة الإنشاء"، يمكنك إجراء ما يلي:

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

المتطلبات

لاستخدام ميزة "اختبار لقطات الشاشة" في ميزة "معاينة الإنشاء"، تحتاج إلى ما يلي:

• المكوّن الإضافي لنظام Gradle المتوافق مع Android‏ 8.5.0-beta01 أو إصدار أحدث
• ‫Kotlin 1.9.20 أو إصدار أحدث ننصحك باستخدام الإصدار 2.0 من Kotlin أو إصدار أحدث حتى تتمكّن من استخدام المكوّن الإضافي Gradle لـ Compose Compiler.

• تفعيل ميزة "الإنشاء" لمشروعك ننصحك بتفعيل Compose باستخدام مكوّن Gradle الإضافي لـ Compose Compiler.

ضبط إعدادات الجهاز

لتفعيل الأداة، اتّبِع الخطوات التالية:

1. أضِف المكوّن الإضافي com.android.compose.screenshot، الإصدار 0.0.1-alpha10 إلى مشروعك.
1. أضِف المكوّن الإضافي إلى ملف كتالوجات الإصدارات:

   [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"}

2. في ملف build.gradle.kts على مستوى الوحدة، أضِف المكوّن الإضافي في مجموعة الترميز plugins {}:

   plugins {
       alias(libs.plugins.screenshot)
   }

2. فعِّل السمة التجريبية في ملف gradle.properties الخاص بمشروعك.

   android.experimental.enableScreenshotTest=true

3. في مجموعة android {} على مستوى الوحدة، فعِّل العلامة التجريبية لاستخدام مجموعة المصدر screenshotTest في ملف build.gradle.kts.

   android {
       experimentalProperties["android.experimental.enableScreenshotTest"] = true
   }
   

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 التالية:

• نظاما التشغيل 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 commandline flag.

0.0.1-alpha06

يقدّم هذا الإصدار ما يلي:

حدّ الاختلاف في الصور: سيسمح لك إعداد الحدّ العام الجديد هذا بالحصول على مزيد من التحكّم في مقارنات لقطات الشاشة. لضبط الإعدادات، عدِّل ملف ‎build.gradle.kts في الوحدة:

android {
    testOptions {
        screenshotTests {
            imageDifferenceThreshold = 0.0001f // 0.01%
        }
    }
}

سيتم تطبيق هذا الحدّ الأدنى على جميع اختبارات لقطات الشاشة المحدّدة في الوحدة.

• إصلاح الأخطاء: تم إصلاح بعض أخطاء أداة عرض الإنشاء، كما تم إتاحة إنشاء رسالة فارغة
• تحسينات الأداء: تم تعديل خوارزمية مقارنة الصور لتكون أسرع