تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

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

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

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

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

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

الشروط

لاستخدام اختبار لقطات الشاشة الخاصة بمعاينة Compose، تحتاج إلى ما يلي:

إصدار Android Gradle 8.5.0-beta01 أو الإصدارات الأحدث
Kotlin 1.9.20 أو إصدار أحدث.

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

لتمكين الأداة، يُرجى اتباع الخطوات التالية:

ثبِّت المكوّن الإضافي com.android.compose.screenshot، الإصدار 0.0.1-alpha01 إلى مشروعك.

أضِف المكوّن الإضافي إلى ملف كتالوجات الإصدارات:

[versions]
agp = "8.5.0-beta01"
kotlin = "1.9.20"
...
screenshot = "0.0.1-alpha01"

[plugins]
...
screenshot = { id = "com.android.compose.screenshot", version.ref = "screenshot"}

في ملف build.gradle.kts على مستوى الوحدة، أضِف المكوّن الإضافي في مجموعة plugins {}:
```
plugins {
    ...
    alias(libs.plugins.screenshot)
}
```

فعِّل الخاصية التجريبية في ملف gradle.properties الخاص بمشروعك.
```
android.experimental.enableScreenshotTest=true
```
في المجموعة android {} من ملف build.gradle.kts على مستوى الوحدة، يمكنك تفعيل العلامة التجريبية لاستخدام مجموعة المصدر screenshotTest والتأكد من ضبط kotlinCompilerExtensionVersion على 1.5.4 أو إصدار أحدث.
ملاحظة: إذا كنت تستخدم Kotlin 2.0 أو إصدارًا أحدث، لن تحتاج إلى ضبط إصدار Compose Compiler بشكل منفصل. يمكنك الاطّلاع على مزيد من المعلومات حول المكوّن الإضافي Compose Compiler Gradle الإضافي.
```
android {
    ...
    composeOptions {
        kotlinCompilerExtensionVersion = "1.5.4"
    }
    experimentalProperties["android.experimental.enableScreenshotTest"] = true
}
```
تأكَّد من إضافة الاعتمادية ui-tooling.
1. يمكنك إضافته إلى كتالوجات الإصدارات:
```
[libraries]
androidx-compose-ui-tooling = { group = "androidx.compose.ui", name = "ui-tooling"}
```
2. أضِفه إلى ملف build.gradle.kts على مستوى الوحدة:
```
dependencies {
  screenshotTestImplementation(libs.androidx.compose.ui.tooling)
}
```

تخصيص معاينات قابلة للإنشاء لاستخدامها في اختبارات لقطات الشاشة

لتحديد المعاينات القابلة للإنشاء التي تريد استخدامها لاختبارات لقطات الشاشة، ضَع المعاينات في فئة اختبار. يجب وضع ملف فئة الاختبار في مجموعة مصادر screenshotTest الجديدة، على سبيل المثال: app/src/screenshotTest/kotlin/com/google/yourapp/ExamplePreviewScreenshots.kt({module}/src/screenshotTest/{kotlin|java}/com/your/package).

يمكنك إضافة المزيد من العناصر القابلة للإنشاء و/أو المعاينات، بما في ذلك المعاينات المتعدّدة، في هذا الملف أو في الملفات الأخرى التي تم إنشاؤها في مجموعة المصدر نفسها.

package com.google.yourapp

import androidx.compose.runtime.Composable
import androidx.compose.ui.tooling.preview.Preview
import com.google.yourapp.ui.theme.MyApplicationTheme

class ExamplePreviewsScreenshots {

    @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/debug/screenshotTest/reference ({module}/src/{variant}/screenshotTest/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.

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

إذا شاركت معاينة في مجموعة المصدر screenshotTest اسم الطريقة المؤهّلة بالكامل مع معاينة في main، يتم استخدام المعاينة بشكل رئيسي بشكل غير صحيح للاختبار بدلاً من اختبار لقطة الشاشة.