تستخدم Google تكنولوجيا الذكاء الاصطناعي لترجمة المحتوى إلى لغتك المفضّلة، وقد تتضمّن بعض الأخطاء.

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

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

مهارات Android

العرض على GitHub

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

استخدِم مهارة Android في testing-setup لوضع استراتيجية اختبار وإنشاء اختبارات لقطات الشاشة.

لتثبيت المهارة من Android CLI، شغِّل:

android skills add testing-setup

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

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

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

دمج بيئة التطوير المتكاملة (IDE)

يمكنك استخدام أداة "اختبار لقطات الشاشة لمعاينة Compose" من خلال تنفيذ مهام Gradle الأساسية (updateScreenshotTest وvalidateScreenshotTest) يدويًا، ولكن يقدّم الإصدار 4 من Android Studio Otter 3 Feature Drop Canary عملية دمج كاملة في بيئة التطوير المتكاملة. يتيح لك ذلك إنشاء صور مرجعية وإجراء اختبارات وتحليل حالات أخطاء في التحقّق ضمن بيئة التطوير المتكاملة. في ما يلي بعض الميزات الرئيسية:

رموز في هامش المحرّر يمكنك الآن إجراء اختبارات أو تعديل الصور المرجعية مباشرةً من رمز المصدر. تظهر رموز التشغيل الخضراء في هامش التحرير بجانب العناصر المركبة والفئات التي تمّت إضافة التعليقات التوضيحية إليها باستخدام @PreviewTest.
- إجراء اختبارات لقطات الشاشة: يمكنك تنفيذ الاختبارات لدالة واحدة أو لفئة بأكملها
- إضافة صور مرجعية أو تعديلها يمكنك بدء مسار تحديث خاص للنطاق المحدّد.

إدارة المراجع التفاعلية: أصبح تعديل الصور المرجعية أكثر أمانًا ودقة.
- مربّع حوار جديد لإنشاء الصور المرجعية: بدلاً من تنفيذ مهمة Gradle مجمّعة، يتيح لك مربّع حوار جديد عرض واختيار المعاينات التي تريد إنشاءها أو تعديلها بدقة.
- معاينة جميع الأشكال يسرد مربّع الحوار جميع أشكال المعاينة (مثل المظهر الفاتح أو الداكن أو الأجهزة المختلفة) بشكل فردي، ما يتيح لك اختيار عناصر معيّنة أو إزالتها قبل إنشاء الصور.

نتائج الاختبارات المتكاملة وعارض الاختلافات يتيح لك عرض النتائج بدون مغادرة بيئة التطوير المتكاملة
- لوحة التشغيل الموحّدة تظهر نتائج اختبار لقطة الشاشة في نافذة الأداة العادية تشغيل. يتم تجميع الاختبارات حسب الفئة والدالة، مع وضع علامة واضحة على حالة النجاح أو الفشل.
- أداة مقارنة مرئية عند تعذُّر الاختبار، تتيح لك علامة التبويب لقطة شاشة مقارنة الصور المرجعية والفعلية والمختلفة جنبًا إلى جنب.
- السمات التفصيلية تقدّم علامة التبويب السمات بيانات وصفية عن الاختبارات التي تعذّر إجراؤها، بما في ذلك نسبة التطابق وأبعاد الصورة وإعدادات المعاينة المحدّدة المستخدَمة (مثل uiMode أو fontScale).

نطاق الاختبار المرن يمكنك الآن تنفيذ اختبارات لقطات الشاشة بنطاقات مختلفة مباشرةً من "عرض المشروع". انقر بزر الماوس الأيمن على وحدة أو دليل أو ملف أو فئة لتشغيل اختبارات لقطات الشاشة الخاصة بهذا العنصر المحدّد.

المتطلبات

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

الإصدار 4 من استوديو Android Panda 1 Canary أو إصدار أحدث
الإصدار 9.0 من المكوّن الإضافي لنظام Gradle المتوافق مع Android (AGP) أو إصدار أحدث
الإصدار 0.0.1-alpha16 أو إصدار أحدث من مكوّن "اختبار لقطات الشاشة لمعاينة Compose" الإضافي
الإصدار 2.2.10 من Kotlin أو إصدار أحدث
الإصدار 17 من JDK أو إصدار أحدث
تفعيل Compose لمشروعك ننصحك بتفعيل Compose باستخدام المكوّن الإضافي Compose Compiler Gradle.

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

الإصدار 8.5.0 أو إصدار أحدث من المكوّن الإضافي لنظام Gradle المتوافق مع Android (AGP)
الإصدار 0.0.1-alpha16 أو إصدار أحدث من مكوّن "اختبار لقطات الشاشة لمعاينة Compose" الإضافي
الإصدار 1.9.20 من Kotlin أو إصدار أحدث ننصحك باستخدام الإصدار 2.0 من Kotlin أو إصدار أحدث حتى تتمكّن من استخدام المكوّن الإضافي Compose Compiler Gradle.
الإصدار 17 من JDK أو إصدار أحدث
تفعيل Compose لمشروعك ننصحك بتفعيل Compose باستخدام المكوّن الإضافي Compose Compiler Gradle.

الإعداد

تعتمد كل من الأداة المدمجة ومهام Gradle الأساسية على المكوّن الإضافي "اختبار لقطات الشاشة لمعاينة Compose". لإعداد المكون الإضافي، اتبع هذه الخطوات:

فعِّل السمة التجريبية في ملف gradle.properties الخاص بمشروعك.
```
android.experimental.enableScreenshotTest=true
```
في حزمة android {} من ملف build.gradle.kts على مستوى الوحدة، فعِّل العلامة التجريبية لاستخدام مجموعة رموز المصدر screenshotTest.
```
android {
    experimentalProperties["android.experimental.enableScreenshotTest"] = true
}
```
أضِف المكوّن الإضافي com.android.compose.screenshot، الإصدار 0.0.1-alpha16 إلى مشروعك.
1. أضف المكوّن الإضافي إلى ملف كتالوجات الإصدارات الخاص بك:
```
[versions]
agp = "9.0.0-rc03"
kotlin = "2.2.10"
screenshot = "0.0.1-alpha16"

[plugins]
screenshot = { id = "com.android.compose.screenshot", version.ref = "screenshot"}
```
2. في ملف build.gradle.kts على مستوى الوحدة، أضِف المكوّن الإضافي في الحزمة plugins {}:
```
plugins {
    alias(libs.plugins.screenshot)
}
```

أضِف الاعتماديتَين screenshot-validation-api وui-tooling.

أضِفها إلى كتالوجات الإصدارات:

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

أضِفها إلى ملف 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.

Android CLI

تنزيل Android CLI

جرِّب Android CLI لعرض معاينة Compose

جرِّب Android CLI إذا لم تكن تستخدم "استوديو Android" أو تفضّل تنفيذ المهام من سطر الأوامر.

على سبيل المثال، استخدِم الأمر android studio render-compose-preview عندما تحتاج إلى عرض معاينة Compose لإجراء اختبار مرئي.

android studio render-compose-preview

في بيئة التطوير المتكاملة (IDE)

انقر على رمز الهامش بجانب دالة @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.

في بيئة التطوير المتكاملة (IDE)

انقر على رمز الهامش بجانب دالة @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.

تحديد المشاكل وحلّها

تُجري أداة "اختبار لقطات الشاشة لمعاينة Compose" اختبارات على جهاز المضيف، والتي يمكن أن تستهلك قدرًا كبيرًا من الذاكرة. يمكنك زيادة الحد الأقصى لحجم الذاكرة المؤقتة لـ JVM المخصّص للاختبار من خلال إضافة السمة التالية إلى ملف gradle.properties:

android.compose.screenshot.maxHeapSize=4g

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

‫Kotlin Multiplatform (KMP): تم تصميم كل من بيئة التطوير المتكاملة والمكوّن الإضافي الأساسي حصريًا لمشاريع Android. ولا تتوافق مع الأنظمة الأساسية غير Android في مشاريع KMP.

يمكنك العثور على القائمة الكاملة بالمشاكل المعروفة الحالية في مكوّن Issue Tracker. يمكنك الإبلاغ عن أي ملاحظات ومشاكل أخرى من خلال Issue Tracker.

التحديثات

للاطّلاع على قائمة كاملة بتحديثات الإصدار، يُرجى مراجعة ملاحظات الإصدار.

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

دمج بيئة التطوير المتكاملة (IDE)

المتطلبات

الإعداد

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

إنشاء صور مرجعية

في بيئة التطوير المتكاملة (IDE)

باستخدام مهام Gradle

إنشاء تقرير اختبار

في بيئة التطوير المتكاملة (IDE)

باستخدام مهام Gradle

تحديد المشاكل وحلّها

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

التحديثات

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