شروع آزمایش با 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: درباره MODEL_ID خاص Android اطلاعات بیشتری دریافت کنید.

  gcloud firebase test android models describe MODEL_ID

  برونداد شامل نمانام مدل دستگاه، سازنده، نسخه‌های سیستم‌عامل، سطوح API پشتیبانی‌شده، میاناهای کاربردی باینری (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»، فرمان نمونه زیر را اجرا کنید:

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 را اجرا کنید.

برای آشنایی با نحوه بررسی نتایج آزمایش از «آزمایش روبات»، به تجزیه‌وتحلیل نتایج آزمایش مراجعه کنید.

اجرا کردن آزمایش ابزارگری

اکنون از ابزار خط فرمان 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"

• اگر فایل 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 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 را باز کنید.

تجزیه‌وتحلیل نتایج آزمایش

پس‌از چند دقیقه، خلاصه ساده‌ای از نتایج آزمایش شما توسط ابزار gcloud چاپ می‌شود:

برونداد اجرای آزمایشی خط فرمان شما همچنین شامل پیوندی برای مشاهده نتایج آزمون است. برای کسب اطلاعات بیشتر درباره نحوه تفسیر این نتایج، به تجزیه‌وتحلیل نتایج Firebase Test Lab برای Android مراجعه کنید.

ورود به سیستم سفارشی و ورودی نوشتاری با آزمون 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 همیشه جدیدترین نسخه Orchestrator را اجرا می‌کند.

• پرچم‌های آزمایش «حلقه بازی»: مجموعه‌ای از پرچم‌های پیکربندی که «حالت نمایشی» را برای شبیه‌سازی کنش‌های بازیکن در برنامه‌های بازی فعال و کنترل می‌کنند. درباره اجرای آزمایش‌های «حلقه بازی» با 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