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

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

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

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

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

دمج بيئة التطوير المتكاملة (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-alpha13 أو إصدار أحدث من مكوّن "اختبار لقطات الشاشة لمعاينة Compose" الإضافي
  • الإصدار 2.2.10 من Kotlin أو إصدار أحدث
  • الإصدار 17 من JDK أو إصدار أحدث
  • تفعيل Compose لمشروعك ننصحك بتفعيل Compose باستخدام المكوّن الإضافي Compose Compiler Gradle.

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

  • الإصدار 8.5.0 أو إصدار أحدث من المكوّن الإضافي لنظام Gradle المتوافق مع Android (AGP)
  • الإصدار 0.0.1-alpha13 أو إصدار أحدث من مكوّن "اختبار لقطات الشاشة لمعاينة Compose" الإضافي
  • الإصدار 1.9.20 من Kotlin أو إصدار أحدث ننصحك باستخدام الإصدار 2.0 من Kotlin أو إصدار أحدث حتى تتمكّن من استخدام المكوّن الإضافي 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-alpha13 إلى مشروعك.
    1. أضف المكوّن الإضافي إلى ملف كتالوجات الإصدارات الخاص بك: 
                [versions]
          agp = "9.0.0-rc03"
          kotlin = "2.1.20"
          screenshot = "0.0.1-alpha13"

          [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 واختَر تشغيل ‎'...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.

التحديثات

0.0.1‎-alpha13

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

  • التوافق مع JDK 17 أو إصدار أحدث
  • إصلاح الأخطاء وتحسين التكامل مع "استوديو Android"

0.0.1‎-alpha12

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

  • التوافق مع الإصدار 9.0 من المكوّن الإضافي لنظام Gradle المتوافق مع Android
  • إتاحة إجراء اختبارات لقطات الشاشة على الإصدار 24 من JDK والإصدارات الأحدث
  • إتاحة ضبط الحد الأقصى لحجم الذاكرة المؤقتة
  • إصلاح أخطاء العرض وتحسين ثبات الاختبار.
  • تحسين التقارير لتشمل الفرق في النسبة المئوية وغيرها من البيانات الوصفية ذات الصلة بالصور الجديدة والصور المرجعية.

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.

  • ستقارن مهمة update{Variant}ScreenshotTest صور العرض الجديدة بالصور المرجعية قبل إجراء التعديل. ولن يتم تعديل سوى الصور التي تتضمّن اختلافات تتجاوز الحدّ الأدنى المحدّد. وتمت إزالة العلامة --updateFilter في سطر الأوامر.

0.0.1‎-alpha06

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

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

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

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

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