بدء الاختبار باستخدام 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 فحصًا للتطبيق من خلال تنفيذ تحليل статиك للمسارات المختلفة من خلال واجهة مستخدم التطبيق، ثم يزحف عبر التطبيق للعثور على الأعطال والمشاكل المحتمَلة الأخرى.

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

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