بدء الاختبار باستخدام 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 أو اختبارات قياس حالة التطبيق.

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

تنبيه: لتجنُّب إنفاق الحصة أو تحصيل الرسوم منك مقابل الاختبارات التي لا تعمل بشكلٍ صحيح، شغِّل منسّق الاختبارات محليًا قبل تجربته في Test Lab. تأكَّد من أنّ منسّق الاختبارات يعمل في تطبيقك من خلال إجراء اختبار على جهازك قبل تحميل ملف APK. ضَع في اعتبارك أنّ إجراء الاختبار باستخدام منسّق الاختبارات يستغرق وقتًا أطول قليلاً من إجراء الاختبار بدونه، وقد يؤثّر ذلك في الفوترة أو يؤدي إلى تجاوز الاختبارات لحدّ المهلة.

يمكنك أيضًا التحكّم في كيفية إجراء 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هي السلسلة النصية. يمكنك أيضًا استخدام هذه العلامة لإخبار Robo بتجاهل عناصر واجهة مستخدِم معيّنة (مثل زر "تسجيل الخروج"). EditText تكون الحقول متاحة، ولكن ليس حقول النصوص في عناصر واجهة مستخدِم WebView.

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

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

تنبيه: لا تستخدِم إلا بيانات اعتماد الحسابات التجريبية غير المرتبطة بـ مستخدمين حقيقيين.

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

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

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

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

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

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

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

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

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

يمكنك استخدام نصوص برمجية للصدفة أو ملفات دفع لأتمتة أوامر اختبار تطبيقات الأجهزة الجوّالة التي كنت ستنفِّذها بخلاف ذلك باستخدام سطر أوامر 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	حدث خطأ في البنية الأساسية للاختبار.