بدء الاختبار باستخدام 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: الحصول على مزيد من المعلومات عن إصدار Android MODEL_ID معيّن

  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 versions list

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

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

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

ملاحظة: أصبح العلامة --device هي الطريقة المفضّلة لتحديد الأجهزة الاختبارية، ولا يجوز استخدامها مع --devices-ids أو --os-version-ids أو --locales أو --orientations. للتعرّف على هذه العلامات القديمة، اطّلِع على قائمة علامات سمات الأجهزة المتوقّفة نهائيًا على الرابط gcloud firebase test android run.

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

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

لإجراء اختبار 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 Test Orchestrator. يتطلّب Orchestrator استخدام الإصدار AndroidJUnitRunner v1.1 أو إصدار أحدث. لتفعيلها، استخدِم gcloud firebase test android run مع العلامة
--use-orchestrator. لإيقاف هذه الميزة، استخدِم العلامة --no-use-orchestrator.

تحذير: لتجنُّب إنفاق الحصة على الاختبارات التي لا تعمل بشكل صحيح أو إصدار فواتير مقابلها، شغِّل أداة Orchestrator على الجهاز قبل تجربتها في Test Lab. تأكَّد من أنّ أوركسترا يعمل داخل تطبيقك من خلال إجراء اختبار على جهازك قبل تحميل ملف APK. وتذكَّر أنّ الاختبار باستخدام 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 للاطّلاع على تقرير تغطية الرمز.

ملاحظة: يؤدي سحب دليل sdcard/Download لكل اختبار إلى وضع جميع الملفات من هذا الدليل في حزمة Cloud Storage للاختبار. إذا كنت مشتركًا في خطة دفع في Blaze وكان تطبيقك ينشئ العديد من الملفات في هذا الدليل، قد يؤدي سحب الدليل إلى تحصيل رسوم إضافية مقابل مساحة التخزين.

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

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

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

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

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

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

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

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

تحذير: استخدِم بيانات الاعتماد للحسابات التجريبية فقط التي لا تكون مرتبطة بمستخدمين حقيقيين.

الطلبات والعلامات المتاحة

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

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

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

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

  ملاحظة: الحدود القصوى للأجهزة الفعلية هي 50 جهازًا، و200 جهازًا لأجهزة Arm الافتراضية، و500 جهازًا لأجهزة x86 الافتراضية. وينطبق ذلك أيضًا على علامة التقسيم اليدوي.

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

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

إنشاء نصوص برمجية لأوامر 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

رمز الخروج	ملاحظات
0	تم اجتياز جميع عمليات التنفيذ الاختبارية.
1	حدث خطأ عام. من بين الأسباب المحتملة لحدوث ذلك: اسم ملف غير موجود أو خطأ في HTTP/الشبكة.
2	تم إنهاء الاختبار بسبب تقديم أوامر أو وسيطات غير معروفة.
10	تعذّر اجتياز حالة اختبار واحدة أو أكثر (الفئات أو طرق الفئات التي تم اختبارها) ضمن تنفيذ اختبار.
15	تعذّر على Firebase Test Lab تحديد ما إذا كانت مصفوفة الاختبار قد اجتازت أو فشلت بسبب حدوث خطأ غير متوقع.
18	لا تتوفّر بيئة الاختبار لتنفيذ هذا الاختبار بسبب سمات الاختبار غير المتوافقة. قد يحدث هذا الخطأ إذا كان مستوى واجهة برمجة التطبيقات لنظام Android المُحدَّد غير متوافق مع نوع الجهاز المحدَّد.
19	تم إلغاء المصفوفة التجريبية من قِبل المستخدم.
20	حدث خطأ في بنية الاختبار الأساسية.