بدء الاختبار باستخدام gcloud CLI

يشرح هذا الدليل كيفية إجراء اختبار قياس الأداء أو Robo أو حلقة الألعاب باستخدام gcloud CLI.

للحصول على قائمة كاملة بأوامر gcloud التي يمكنك استخدامها مع تطبيق Android في Test Lab، يُرجى الانتقال إلى المستندات المرجعية لـ gcloud firebase test android.

قبل البدء

أضِف Firebase إلى مشروع Android الخاص بك، في حال لم يسبق لك إجراء ذلك.

الخطوة 1: إعداد gcloud CLI

1. نزِّل Google Cloud SDK

ويشمل ذلك أداة gcloud CLI.

2. تأكَّد من أنّ عملية التثبيت محدَّثة:

   gcloud components update
   

3. سجِّل الدخول إلى gcloud CLI باستخدام حساب Google:

   gcloud auth login
   

4. اضبط مشروع Firebase في gcloud، حيث PROJECT_ID هو رقم تعريف مشروعك على Firebase:

   gcloud config set project PROJECT_ID
   

الخطوة 2: الاطّلاع على الأجهزة الاختبارية المتاحة

استخدِم أوامر gcloud التالية لعرض الأجهزة الاختبارية واللغات المتاحة للاختبار.

يمكنك أيضًا تنزيل نموذج تطبيق Notepad لبدء تشغيل الأوامر على الفور. استخدِم الملف الثنائي app-debug-unaligned.apk وملف اختبارات قياس حالة التطبيق app-debug-test-unaligned.apk، الموجودَين في NotePad/app/build/outputs/apk/.

• ‫models list: يمكنك الحصول على قائمة حالية بأجهزة Android المتاحة لك لإجراء الاختبارات عليها.

  gcloud firebase test android models list

  في ناتج الأمر:

  • يحتوي العمود MODEL_ID على المعرّف الذي يمكنك استخدامه لاحقًا لإجراء الاختبارات على طراز الجهاز.
  • يحتوي العمود OS_VERSION_ID على إصدارات نظام التشغيل المتوافقة مع الجهاز.

  مثال على الناتج

  

• ‫models describe: الحصول على مزيد من المعلومات حول MODEL_ID معيّن في Android

  gcloud firebase test android models describe MODEL_ID

  يتضمّن الناتج العلامة التجارية لطراز الجهاز والشركة المصنّعة وإصدارات نظام التشغيل ومستويات واجهة برمجة التطبيقات المتوافقة وواجهات التطبيق الثنائية (ABI) المتوافقة وتواريخ الإصدار وما إذا كان الجهاز فعليًا أو افتراضيًا.

• versions list: يمكنك الحصول على قائمة بإصدارات أنظمة التشغيل المتاحة حاليًا لإجراء الاختبارات عليها.

  gcloud firebase test android versions list

  يمكنك استخدام معرّف من أي من العمودين الأولين من ناتج الأمر (OS_VERSION_ID وVERSION)، لإجراء اختبارات لاحقًا على إصدار نظام التشغيل Android. إذا لم تحدّد إصدارات نظام التشغيل Android التي تريد إجراء الاختبار عليها، سيتم استخدام الإصدار التلقائي المذكور ضمن عمود TAGS.

  مثال على الناتج

  

• ‫locales list: يمكنك الحصول على القائمة الحالية للغات المتاحة للاختبار.

  gcloud firebase test android locales list

  يحتوي العمود الأول من ناتج الأمر، LOCALE، على المعرّف الذي يمكنك استخدامه لاحقًا لإجراء اختبارات على لغة معيّنة. إذا لم تحدّد اللغات التي تريد إجراء الاختبار بها، سيتم استخدام اللغة الإنجليزية كلغة تلقائية.

الخطوة 3: إجراء الاختبار

بعد أن تعرّفت على مجموعة طُرز الأجهزة واللغات وإصدارات نظام التشغيل المتاحة لاختبار تطبيقك، يمكنك تحديد الأجهزة باستخدام الأمر gcloud firebase test android run والعلامة --device لإجراء اختبارات Robo أو اختبارات لقياس حالة التطبيق.

إجراء اختبار Robo

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

لتشغيل اختبار Robo، نفِّذ الأمر النموذجي التالي:

gcloud firebase test android run \
  --type robo \
  --app app-debug-unaligned.apk \
  --device model=Nexus6,version=21,locale=en,orientation=portrait  \
  --device model=Nexus7,version=19,locale=fr,orientation=landscape \
  --timeout 90s \
  --client-details matrixLabel="Example matrix label"

• تكون المَعلمة --type robo ضمنية في حال عدم تحديد قيمة --type.
• لمساعدتك في تحديد المصفوفات التجريبية والعثور عليها في وحدة تحكُّم Firebase، يمكنك استخدام العلامة الاختيارية --client-details matrixLabel="Example matrix label" لتصنيف المصفوفة التجريبية.
• يمكنك الاطّلاع على المجموعة الكاملة من خيارات سطر الأوامر لتشغيل الاختبارات عن طريق كتابة: gcloud help firebase test android run.

كبديل لتحديد هذه الوسيطات في سطر الأوامر، يمكنك اختياريًا تحديد الوسيطات في ملف وسيطات بتنسيق YAML. يمكنك تشغيل gcloud topic arg-files لمعرفة كيفية استخدام هذه الميزة.

لمعرفة كيفية التحقيق في نتائج الاختبار من اختبار Robo، يُرجى الاطّلاع على تحليل نتائج الاختبار.

إجراء اختبار قياس حالة التطبيق

استخدِم الآن أداة سطر الأوامر gcloud لإجراء اختبارات Espresso على تطبيق Notepad على إعدادات أجهزة Android المحدّدة. استخدِم نوع الاختبار instrumentation لتشغيل الاختبارات في app-debug-test-unaligned.apk على النحو التالي:

gcloud firebase test android run \
  --type instrumentation \
  --app app-debug-unaligned.apk \
  --test app-debug-test-unaligned.apk \
  --device model=Nexus6,version=21,locale=en,orientation=portrait  \
  --device model=Nexus7,version=19,locale=fr,orientation=landscape
  --client-details matrixLabel="Example matrix label"

• تكون مَعلمة حالة التطبيق --type ضمنية إذا تم تحديد حزمة APK للاختبار باستخدام --test.
• لمساعدتك في تحديد المصفوفات التجريبية وتحديد موقعها في وحدة تحكّم Firebase، يمكنك استخدام علامة --client-details matrixLabel="Example matrix label" الاختيارية لتصنيف المصفوفة التجريبية.
• يمكنك الاطّلاع على المجموعة الكاملة من خيارات سطر الأوامر لتشغيل الاختبارات من خلال كتابة gcloud help firebase test android run.

كبديل لتحديد هذه الوسيطات في سطر الأوامر، يمكنك اختياريًا تحديد الوسيطات في ملف وسيطات بتنسيق YAML. يمكنك تشغيل gcloud topic arg-files لمعرفة كيفية استخدام هذه الميزة.

تتيح gcloud CLI استخدام منسّق الاختبارات من Android. يتطلّب Orchestrator الإصدار 1.1 من AndroidJUnitRunner أو إصدارًا أحدث. لتفعيلها، استخدِم gcloud firebase test android run مع علامة
--use-orchestrator. لإيقافها، استخدِم العلامة --no-use-orchestrator.

يمكنك أيضًا التحكّم في كيفية تشغيل Test Lab لاختبارات قياس حالة التطبيق باستخدام علامات إضافية غير معروضة أعلاه. على سبيل المثال، يمكنك استخدام العلامة --test-targets لاختبار فئة واحدة أو طريقة فئة تستخدمها حزمة APK الخاصة بالاختبار. يمكنك أيضًا معرفة ما إذا كان الاختبار الذي تعذّر إجراؤه غير مستقر أم لا باستخدام العلامة --num-flaky-test-attempts التي تحدّد عدد المرات التي يجب فيها إعادة محاولة تنفيذ الاختبار في حال تعذّر إجراء إطار اختبار واحد أو أكثر لأي سبب. لمزيد من المعلومات، يُرجى الاطّلاع على gcloud firebase test android run.

تقارير نسبة استخدام رموز الصفحة لاختبارات قياس حالة التطبيق

يتيح Test Lab استخدام أدوات إعداد تقارير نسبة استخدام رموز الصفحة EMMA وJaCoCo. إذا كانت لديك أي من الأداتين مدمجة في إصدار تطبيقك، يمكنك الحصول على تقرير نسبة استخدام رموز الصفحة لاختبارات Test Lab من خلال تشغيل gcloud firebase test android run مع بعض الوسيطات الإضافية. إذا لم يتم تفعيل "منسّق الاختبارات من Android"، استخدِم ما يلي:

gcloud firebase test android run \
  --type instrumentation \
  --app your-app.apk \
  --test your-app-test.apk \
  --device model=TestDevice,version=AndroidVersion  \
  --environment-variables coverage=true,coverageFile="/sdcard/Download/coverage.ec" \
  --directories-to-pull /sdcard/Download

إذا كنت تنشئ تقارير حول نسبة استخدام رموز الصفحة أثناء استخدام "منسّق الاختبارات من Android"، عليك تعديل متغيّرات البيئة على النحو التالي:

gcloud firebase test android run \
  --type instrumentation \
  --app your-app.apk \
  --test your-app-test.apk \
  --device model=TestDevice,version=AndroidVersion  \
  --environment-variables clearPackageData=true,coverage=true,coverageFilePath="/sdcard/Download/" \
  --directories-to-pull /sdcard/Download

عندما ينتهي Test Lab من إجراء الاختبارات، يمكنك العثور على تقارير نسبة استخدام رموز الصفحة في Google Cloud Storage:

1. افتح رابط وحدة تحكّم Firebase الذي طبعته أداة gcloud أعلى جدول نتائج الاختبار في الوحدة الطرفية.
2. انقر على تنفيذ تجريبي من القائمة في هذا الرابط لفتح صفحة تفاصيل هذا التنفيذ.
3. انقر على نتائج الاختبار للانتقال إلى حزمة Cloud Storage التي تتضمّن نتائج اختبار عملية التنفيذ هذه.
4. افتح artifacts/coverage.ec للاطّلاع على تقرير نسبة استخدام رموز الصفحة.

تحليل نتائج الاختبار

بعد بضع دقائق، تتم طباعة ملخّص أساسي لنتائج الاختبار من خلال أداة gcloud:

يتضمن ناتج تشغيل اختبار سطر الأوامر أيضًا رابطًا لعرض نتائج الاختبار. لمزيد من المعلومات حول كيفية تفسير هذه النتائج، يُرجى الاطّلاع على مقالة تحليل نتائج "Firebase Test Lab" لأجهزة Android.

تسجيل الدخول المخصّص وإدخال النص باستخدام اختبار Robo

يُكمل اختبار Robo تلقائيًا شاشات تسجيل الدخول التي تستخدم حساب Google للمصادقة، ما لم تستخدم المَعلمة --no-auto-google-login. ويمكنه أيضًا إكمال شاشات تسجيل الدخول المخصّصة باستخدام بيانات اعتماد الحساب التجريبي التي تقدّمها. يمكنك أيضًا استخدام هذه المَعلمة لتقديم نص إدخال مخصّص لحقول نصية أخرى يستخدمها تطبيقك.

لإكمال حقول النص في تطبيقك، استخدِم المَعلمة --robo-directives وقدِّم قائمة قيم مفصولة بفاصلة لأزواج key-value، حيث key هو اسم مورد Android لعنصر في واجهة المستخدم المستهدَف، وvalue هو السلسلة النصية. يمكنك أيضًا استخدام هذه العلامة لإعلام Robo بتجاهل عناصر معيّنة في واجهة المستخدم (مثل زر "تسجيل الخروج"). تتوفّر حقول EditText، ولكن لا تتوفّر حقول نصية في عناصر واجهة المستخدم WebView.

على سبيل المثال، يمكنك استخدام المَعلمة التالية لتسجيل الدخول المخصّص:

--robo-directives username_resource=username,password_resource=password

الأوامر والعلامات المتاحة

تتوفّر في واجهة سطر الأوامر Test Lab gcloud عدة أوامر وعلامات تتيح لك إجراء الاختبارات بمواصفات مختلفة:

• علامة منسّق الاختبارات من Android: علامة لتفعيل منسّق الاختبارات، وهو أداة تتيح لك إجراء كل اختبار من اختبارات تطبيقك في استدعاء خاص به لـ Instrumentation. يستخدم Test Lab دائمًا أحدث إصدار من Orchestrator.

• علامات اختبار حلقة الألعاب: هي مجموعة من علامات الضبط التي تفعّل "الوضع التجريبي" وتتحكّم فيه لمحاكاة إجراءات اللاعبين في تطبيقات الألعاب. مزيد من المعلومات حول إجراء اختبارات حلقة الألعاب باستخدام Test Lab

• علامة التقسيم الموحّد (في مرحلة تجريبية): علامة تحدّد عدد الأجزاء التي تريد توزيع أُطر الاختبار عليها بالتساوي. يتم تشغيل الأجزاء بالتوازي على أجهزة منفصلة.

• علامة التقسيم اليدوي (في مرحلة تجريبية): علامة تحدّد مجموعة من الحِزم و/أو الفئات و/أو أُطر الاختبار لتشغيلها في جزء (مجموعة من أُطر الاختبار). ويتم تشغيل الأجزاء بالتوازي على أجهزة منفصلة.

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

كتابة نصوص برمجية لأوامر gcloud باستخدام Test Lab

يمكنك استخدام نصوص shell البرمجية أو ملفات الدفعات لتنفيذ أوامر اختبار التطبيقات المتوافقة مع الأجهزة الجوّالة بشكل آلي، والتي كنت ستنفّذها باستخدام سطر أوامر gcloud. ينفّذ النص البرمجي التالي بلغة bash اختبار قياس حالة التطبيق مع مهلة دقيقتَين، ويُبلغ عمّا إذا اكتمل الاختبار بنجاح:

if gcloud firebase test android run --app my-app.apk --test my-test.apk --timeout 2m
then
    echo "Test matrix successfully finished"
else
    echo "Test matrix exited abnormally with non-zero exit code: " $?
fi

رموز الخروج من النص البرمجي

يوفّر Test Lab العديد من رموز الخروج التي يمكنك استخدامها لفهم نتائج الاختبارات التي تجريها باستخدام النصوص البرمجية أو ملفات الدفعات بشكل أفضل.

رموز الخروج من النصوص البرمجية لـ Test Lab