شروع آزمایش با gcloud CLI

این راهنما نحوه اجرای آزمایش ابزار دقیق، Robo، یا «حلقه بازی» را بااستفاده از gcloud CLI شرح می‌دهد.

برای مشاهده فهرست کامل فرمان‌های gcloud که می‌توانید با برنامه Android در Test Lab استفاده کنید، به اسناد مرجع gcloud firebase test android مراجعه کنید.

قبل از شروع

اگر قبلاً این کار را نکرده‌اید، Firebase را به پروژه Android خود اضافه کنید.

مرحله ۱. راه‌اندازی gcloud CLI

1. کیت توسعه نرم‌افزار Google Cloud را بارگیری کنید

این شامل ابزار gcloud CLI می‌شود.

2. مطمئن شوید نصب به‌روز باشد:

   gcloud components update
   

3. بااستفاده از «حساب Google» خود به سیستم gcloud CLI وارد شوید:

   gcloud auth login
   

4. پروژه Firebase خود را در gcloud تنظیم کنید، جایی که PROJECT_ID شناسه پروژه Firebase شما است:

   gcloud config set project PROJECT_ID
   

مرحله ۲. بررسی دستگاه‌های آزمایشی دردسترس

از فرمان‌های 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 locales list

  ستون اول خروجی فرمان، LOCALE، حاوی شناسه‌ای است که می‌توانید بعداً برای اجرای آزمایش‌ها درمقابل یک منطقه زبانی استفاده کنید. اگر مناطق زبانی را برای آزمایش مشخص نکنید، از انگلیسی به‌عنوان منطقه زبانی پیش‌فرض استفاده می‌شود.

مرحله ۳. اجرای آزمایش

اکنون که با طیف مدل‌های دستگاه، زبان‌های محلی، و نسخه‌های سیستم‌عامل دردسترس برای آزمایش برنامه‌تان آشنا شدید، می‌توانید دستگاه‌ها را بااستفاده از فرمان 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 مشخص نشده باشد، پارامتر --type robo ضمنی است.
• برای کمک به شناسایی و یافتن ماتریس‌های آزمایشی در کنسول 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"

• اگر APK آزمایشی با --test مشخص شده باشد، پارامتر ابزارگری --type ضمنی است.
• برای کمک به شما در شناسایی و یافتن ماتریس‌های آزمایشی در کنسول 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 نسخه ۱.۱ یا بالاتر نیاز دارد. برای فعال کردن آن، از 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 پشتیبانی می‌کند. اگر هرکدام از این ابزارها را در ساخت برنامه‌تان ادغام کرده‌اید، می‌توانید با اجرای gcloud firebase test android run با چند آرگومان اضافی، گزارش پوشش کد را برای آزمایش‌های Test Lab دریافت کنید. اگر «هماهنگ‌کننده آزمایش 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 رشته نوشتاری است. همچنین می‌توانید از این پرچم برای گفتن به 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 بیشتر بدانید.

• پرچم Uniform Sharding (در نسخه بتا): پرچمی که تعداد بخش‌هایی را که می‌خواهید چارچوب‌های تست به‌طور مساوی در آن‌ها توزیع شود مشخص می‌کند. تکه‌ها به‌طور موازی در دستگاه‌های جداگانه اجرا می‌شوند.

• پرچم «تکه‌بندی دستی» (در نسخه بتا): پرچمی که گروهی از بسته‌ها، کلاس‌ها، و/یا چارچوب‌های تست را برای اجرا در یک تکه (گروهی از چارچوب‌های تست) مشخص می‌کند. تکه‌ها به‌طور موازی در دستگاه‌های جداگانه اجرا می‌شوند.

• پرچم نمایه‌های ترافیک شبکه (در نسخه بتا): پرچمی که مشخص می‌کند آزمایش‌های شما از کدام نمایه شبکه با دستگاه‌های فیزیکی استفاده می‌کنند. نمایه‌های شبکه انواع شرایط شبکه را شبیه‌سازی می‌کنند و به شما امکان می‌دهند عملکرد برنامه‌تان را در شبکه‌های غیرقابل‌اعتماد یا غیرقابل‌پیش‌بینی آزمایش کنید.

اسکریپت‌نویسی فرمان‌های 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