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

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

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

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

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

المتطلبات

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

• الإصدار 8.5.0 من المكوّن الإضافي لنظام Gradle المتوافق مع Android أو إصدار أحدث
• الإصدار 1.9.20 من Kotlin أو إصدار أحدث ننصحك باستخدام الإصدار 2.0 من Kotlin أو إصدار أحدث حتى تتمكّن من استخدام المكوّن الإضافي Compose Compiler Gradle.
• الإصدار 23 من حزمة تطوير Java أو الإصدارات الأقدم

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

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

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

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-alpha11 إلى مشروعك.
   1. أضِف المكوّن الإضافي إلى ملف قوائم الإصدارات:

                [versions]
                agp = "8.11.0-alpha06"
                kotlin = "2.1.20"
                screenshot = "0.0.1-alpha11"
      
                [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 التالية:

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

يتضمّن هذا الإصدار ما يلي:

• التوافق مع الإصدار 8.13 من المكوّن الإضافي لنظام Gradle المتوافق مع Android
• أضفنا إمكانية تحليل عناصر XML قابلة للرسم تتضمّن قيمًا عشرية بغض النظر عن اللغة المحلية للجهاز المضيف.
• بالنسبة إلى الجهاز المضيف الذي يستخدم JDK 24 أو إصدارًا أحدث، سيتم اختيار JDK متوافق (11-23)، شرط أن يكون مثبّتًا.

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 وإتاحة استخدام Compose فارغ
• تحسينات الأداء: تم تعديل خوارزمية مقارنة الصور لتصبح أسرع