اختبار لقطات الشاشة باستخدام مجموعات الاختبار

بدءًا من الإصدار 9.5.0-alpha03 من "المكوّن الإضافي لنظام Gradle المتوافق مع Android" (AGP) والإصدار 0.0.1-alpha16 من محرك "اختبار لقطات الشاشة لمعاينة Compose"، يتم دمج اختبار لقطات الشاشة مع إطار عمل حِزم الاختبار الأصلي في "المكوّن الإضافي لنظام Gradle المتوافق مع Android".

يحلّ هذا الأسلوب محل المكوّن الإضافي المستقل الخاص بلقطات الشاشة (com.android.compose.screenshot). وننصحك باستخدام مجموعات اختبارات AGP للأسباب التالية:

• دورة حياة مهمة Gradle الأصلية: تتكامل اختبارات لقطات الشاشة مباشرةً مع دورات حياة الاختبارات العادية في Gradle وAGP، ما يؤدي إلى تحسين عزل المهام وموثوقية تنفيذ الاختبارات.
• إتاحة حِزم متعددة الإصدارات وحِزم مخصّصة: يمكنك إنشاء حِزم اختبار لقطات شاشة متعددة ومختلفة (مثل screenshotTest أو uiTests أو smokeTests) ضمن وحدة واحدة واستهداف نُسخ إصدار محددة (مثل demoDebug أو release)، بدلاً من أن يقتصر الأمر على مجموعة رموز مصدر واحدة تم إعدادها مسبقًا.
• تحسين أداء الإنشاء والعزل: تستخدم مجموعات اختبارات AGP عمليات تحويل عناصر مدمجة (مثل استخراج وقت تشغيل Layoutlib) وتحميل الفئات المعزول، مع توفير الدعم الكامل لميزة "التخزين المؤقت للإعداد" في Gradle وميزة "عزل المشاريع".

android skills add testing-setup

المتطلبات

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

• الإصدار 4 أو إصدار أحدث من استوديو Android Rabbit 1 Canary
• الإصدار 9.5.0-alpha03 أو إصدار أحدث من المكوّن الإضافي لنظام Gradle المتوافق مع Android
• الإصدار 0.0.1-alpha16 أو إصدار أحدث من "محرك لقطات الشاشة في Compose"
• الإصدار 17 أو إصدار أحدث من JDK
• تفعيل Compose لمشروعك ننصحك بتفعيل Compose باستخدام المكوّن الإضافي Compose Compiler Gradle.

الإعداد والضبط

لضبط اختبار لقطات الشاشة في Compose باستخدام مجموعات الاختبار، أكمِل الخطوات التالية:

1. تفعيل العلامات التجريبية

في ملف gradle.properties الجذر الخاص بمشروعك، فعِّل اختبار لقطات الشاشة وتوافق حزمة الاختبار:

android.experimental.enableScreenshotTest=true
android.experimental.testSuiteSupport=true

2. ضبط مجموعة الاختبارات في ملف build.gradle.kts

في ملف build.gradle.kts الخاص بالوحدة، حدِّد مجموعة اختبارات لقطات الشاشة ضمن الحزمة testOptions:

android {
    testOptions {
        screenshotTests.create("screenshotTest") { // suiteName can be customized (for example, "uiTests")
            engineVersion = "0.0.1-alpha16"
            targetVariants.add("demoDebug") // Add specific variants to test

            dependencies {
                implementation(libs.androidx.compose.ui.tooling)
                implementation("com.android.tools.screenshot:screenshot-validation-api:0.0.1-alpha16")
            }
        }
    }
}

3- إنشاء مجموعة رموز المصدر الاختبارية

أنشئ دليل مجموعة رموز المصدر مخصّصًا يتطابق مع اسم حزمتك:

{module}/src/{suiteName}/kotlin/

على سبيل المثال، بالنسبة إلى حزمة باسم screenshotTest:

feature/foryou/impl/src/screenshotTest/kotlin/com/example/app/ForYouScreenTest.kt

4. تحديد اختبارات المعاينات القابلة للإنشاء

أضِف التعليقات التوضيحية @PreviewTest و@Preview العادية أو التعليقات التوضيحية الخاصة بالمعاينات المتعددة إلى العناصر القابلة للإنشاء:

package com.example.app

import androidx.compose.runtime.Composable
import androidx.compose.ui.tooling.preview.Preview
import com.android.tools.screenshot.PreviewTest
import com.example.app.ui.theme.AppTheme

@PreviewTest
@Preview(showBackground = true)
@Composable
fun ForYouScreenPreview() {
    AppTheme {
        ForYouScreen(isSyncing = false)
    }
}

إجراء اختبارات لقطات الشاشة

تنشئ مجموعات اختبارات "مكوّن Android الإضافي لبرنامج Gradle" مهام Gradle مخصّصة استنادًا إلى اسم المجموعة والهدف والصيغ.

1. إنشاء صور مرجعية أو تعديلها

عرض معاينات قابلة للإنشاء وتخزين الصور المرجعية الأساسية:

• نظاما التشغيل Linux وmacOS: ./gradlew update{SuiteName}{Target}{Variant}TestSuite (على سبيل المثال، ./gradlew updateScreenshotTestDefaultDemoDebugTestSuite)
• Windows: gradlew updateScreenshotTestDefaultDemoDebugTestSuite

يتم إنشاء الصور المرجعية وحفظها في:

{module}/src/{suiteName}{Target}{Variant}/reference/

2. التحقّق من صحة الاختبارات وإجراؤها

عرض لقطات شاشة جديدة ومقارنتها بالصور المرجعية:

• نظاما التشغيل Linux وmacOS: ./gradlew test{SuiteName}{Target}{Variant}TestSuite (على سبيل المثال، ./gradlew testScreenshotTestDefaultDemoDebugTestSuite)
• Windows: gradlew testScreenshotTestDefaultDemoDebugTestSuite

فحص تقارير الاختبار

في حال رصد اختلافات أو تعذُّر إجراء الاختبارات، ينشئ "مكوّن Android الإضافي لبرنامج Gradle" تقرير اختبار بتنسيق HTML.

• موقع التقرير: {module}/build/reports/tests/{taskName}/index.html (مثلاً، app/build/reports/tests/testScreenshotTestDefaultDemoDebugTestSuite/index.html)

يتضمّن التقرير المعدَّل ما يلي:

• بطاقة البيانات الوصفية للعنوان: تعرض اسم الاختبار وطريقة المعاينة والبديل والمجموعة وشارة الحالة.
• تصنيف الأخطاء: يتم بوضوح وضع علامة Reference Image Missing أو Image Size Mismatch أو Pixel Mismatch مع تتبُّع تسلسل استدعاء الدوال البرمجية القابل للنسخ.
• ميزة "الاختلاف المرئي الديناميكي": تعمل على تمييز التعديلات الطفيفة باستخدام تباين منخفض، والتغييرات الكبيرة باستخدام تباين عالٍ لمنع تجاهل العناصر المتداخلة.

نقل البيانات من المكوّن الإضافي المستقل القديم

للانتقال من المكوّن الإضافي القديم المستقل للقطات الشاشة إلى حِزم اختبار Android Gradle Plugin، عدِّل إعدادات Gradle وأوامر المهام.

مقارنة DSL لإعدادات التصميم

المكوّن الإضافي المستقل القديم (متوقف)

// In build.gradle.kts
plugins {
    alias(libs.plugins.screenshot)
}

dependencies {
    screenshotTestImplementation(libs.androidx.compose.ui.tooling)
    screenshotTestImplementation("com.android.tools.screenshot:screenshot-validation-api:0.0.1-alpha16")
}

مجموعات اختبار Android Gradle Plugin (يُنصح بها)

// In build.gradle.kts
android {
    testOptions {
        screenshotTests.create("screenshotTest") {
            engineVersion = "0.0.1-alpha16"
            targetVariants.add("demoDebug")

            dependencies {
                implementation(libs.androidx.compose.ui.tooling)
                implementation("com.android.tools.screenshot:screenshot-validation-api:0.0.1-alpha16")
            }
        }
    }
}

ربط المهام والمسارات