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

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

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

قبل البدء

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

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

1. تنزيل Google Cloud SDK

ويشمل ذلك أداة سطر الأوامر gcloud.

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 التالية لعرض الأجهزة الاختبارية واللغات المتوفّرة للاختبار.

يمكنك أيضًا تنزيل نموذج تطبيق "المفكرة" لبدء تنفيذ الأوامر على الفور. استخدِم ملف الرمز الثنائي 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

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

• 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 لتطبيق "المفكرة" على إعدادات جهاز 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 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 للاطّلاع على تقرير تغطية الرمز.

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

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

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

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

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

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

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