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

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

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

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

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

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

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

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

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

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

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

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