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

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

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

قبل البدء

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

الخطوة 1. إعداد واجهة سطر الأوامر في gcloud

1. نزِّل حزمة تطوير البرامج (SDK) لخدمة Google Cloud.

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

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

تقارير تغطية الرمز لاختبارات الأدوات

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

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 Test Orchestrator أيضًا، يمكنك تعديل متغيّرات البيئة على النحو التالي:

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

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

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

  ملاحظة: الحدّ الأقصى المسموح به للأجهزة الفعلية هو 50 و200 للذراع الافتراضية و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

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