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

يوضّح هذا الدليل كيفية إجراء اختبار باستخدام قياس حالة التطبيق أو Robo أو حلقة الألعاب باستخدام 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

  تحتوي النتائج على العلامة التجارية وطراز الجهاز والشركة المصنّعة وإصدارات نظام التشغيل ومستويات واجهة برمجة التطبيقات المتوافقة وواجهات التطبيق الثنائية المتوافقة (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 أو اختبارات الأجهزة.

إجراء اختبار 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 أيضًا، عدِّل متغيرات البيئة على النحو التالي:

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": علامة لتفعيل منسّق الاختبارات، وهي أداة تتيح لك إجراء كل اختبار من اختبارات تطبيقك في استدعاء خاص به لقياس حالة التطبيق 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