آزمایش را با 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 CLI است.

2. اطمینان حاصل کنید که نصب شما به روز است:

   gcloud components update
   

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

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

  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 versions list
  

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

مرحله 3. آزمون خود را اجرا کنید

اکنون که دامنه مدل‌های دستگاه، زبان‌های محلی و نسخه‌های سیستم‌عامل موجود برای آزمایش برنامه خود را می‌دانید، می‌توانید دستگاه‌ها را با استفاده از دستور gcloud firebase test android run و پرچم --device برای اجرای تست‌های Robo یا ابزار دقیق مشخص کنید.

توجه: پرچم --device اکنون روش ترجیحی برای تعیین دستگاه های آزمایشی است و ممکن است در ارتباط با --devices-ids ، --os-version-ids ، --locales یا --orientations استفاده نشود. برای آشنایی با این پرچم‌های قدیمی، فهرست پرچم‌های بعد دستگاه منسوخ شده را در gcloud firebase test android run ببینید.

تست 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 برای اجرای تست‌های اسپرسو برنامه Notepad در تنظیمات دستگاه اندرویدی خود استفاده کنید. از نوع تست 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 نسخه 1.1 یا بالاتر نیاز دارد. برای فعال کردن آن، gcloud firebase test android run با استفاده کنید
--use-orchestrator . برای غیرفعال کردن آن از پرچم --no-use-orchestrator استفاده کنید.

احتیاط: برای جلوگیری از صرف سهمیه در تست‌های نادرست یا دریافت صورت‌حساب، Orchestrator را قبل از امتحان در Test Lab به صورت محلی اجرا کنید. قبل از آپلود APK، با اجرای آزمایشی روی دستگاه خود، تأیید کنید که Orchestrator در برنامه شما کار می کند. به خاطر داشته باشید که آزمایش با ارکستراتور کمی بیشتر از بدون آن طول می‌کشد و ممکن است بر صورت‌حساب شما تأثیر بگذارد یا باعث شود که آزمایش‌های شما از محدودیت زمانی شما فراتر رود.

همچنین می‌توانید با استفاده از پرچم‌های اضافی که در بالا نشان داده نشده‌اند، نحوه اجرای تست‌های ابزار دقیق را Test Lab کنترل کنید. برای مثال، می‌توانید از پرچم --test-targets برای آزمایش یک کلاس یا روش کلاسی که توسط APK آزمایشی شما استفاده می‌شود، استفاده کنید. همچنین می‌توانید با استفاده از پرچم --num-flaky-test-attempts ، که تعداد دفعاتی را که یک یا چند مورد از آزمایش‌های آن یک یا چند مورد آزمایشی آن اجرا می‌شود، باید مجدداً انجام شود، متوجه شوید که آیا آزمون شما شکست خورده واقعاً پوسته‌دار بوده است یا خیر. به هر دلیلی شکست بخورد برای کسب اطلاعات بیشتر، اجرای تست gcloud firebase android را ببینید.

گزارش های پوشش کد برای تست های ابزار دقیق

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. روی Test Results کلیک کنید تا به سطل Cloud Storage با نتایج آزمایش آن اجرا بروید.
4. برای مشاهده گزارش پوشش کد خود artifacts/coverage.ec باز کنید.

توجه: کشیدن دایرکتوری sdcard/Download برای هر آزمایش، همه فایل‌ها را از آن دایرکتوری در سطل Cloud Storage آزمون قرار می‌دهد. اگر در برنامه پرداخت Blaze هستید و برنامه شما فایل‌های زیادی را در آن فهرست ایجاد می‌کند، کشیدن فهرست ممکن است هزینه‌های ذخیره‌سازی اضافی را به همراه داشته باشد.

نتایج آزمایش خود را تجزیه و تحلیل کنید

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

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

ورود سفارشی و ورودی متن با تست Robo

تست Robo به طور خودکار صفحات ورود به سیستم را تکمیل می کند که از یک حساب Google برای احراز هویت استفاده می کنند، مگر اینکه از پارامتر --no-auto-google-login استفاده کنید. همچنین می‌تواند صفحه‌های ورود سفارشی را با استفاده از اعتبارنامه‌های حساب آزمایشی که ارائه می‌دهید تکمیل کند. همچنین می توانید از این پارامتر برای ارائه متن ورودی سفارشی برای سایر فیلدهای متنی مورد استفاده توسط برنامه خود استفاده کنید.

برای تکمیل فیلدهای متنی در برنامه خود، از پارامتر --robo-directives استفاده کنید و فهرستی از جفت‌های key-value جدا شده با کاما ارائه دهید، که در آن key ، نام منبع Android عنصر UI هدف و value آن رشته متن است. . همچنین می‌توانید از این پرچم استفاده کنید تا به Robo بگویید عناصر رابط کاربری خاص را نادیده بگیرد (مثلاً دکمه "خروج"). فیلدهای EditText پشتیبانی می شوند اما فیلدهای متنی در عناصر WebView UI پشتیبانی نمی شوند.

به عنوان مثال، می توانید از پارامتر زیر برای ورود سفارشی استفاده کنید:

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

احتیاط: فقط برای حساب های آزمایشی که با کاربران واقعی مرتبط نیستند از اعتبارنامه ها استفاده کنید.

دستورات و پرچم های موجود

Test Lab gcloud CLI دارای چندین دستور و پرچم در دسترس است که به شما امکان می دهد آزمایش هایی را با مشخصات مختلف اجرا کنید:

• پرچم ارکستراتور تست اندروید : پرچمی برای فعال کردن ارکستراتور، ابزاری که به شما امکان می‌دهد هر یک از آزمایش‌های برنامه خود را با فراخوانی Instrumentation اجرا کنید. Test Lab همیشه آخرین نسخه ارکستراتور را اجرا می کند.

• پرچم‌های تست حلقه بازی : مجموعه‌ای از پرچم‌های پیکربندی که یک "حالت نمایشی" را برای شبیه‌سازی اقدامات بازیکن در برنامه‌های بازی فعال و کنترل می‌کند. درباره اجرای تست های Game Loop با Test Lab بیشتر بیاموزید.

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

  توجه: محدودیت برای دستگاه های فیزیکی 50، 200 برای Arm virtual و 500 برای x86 مجازی است. این همچنین در مورد پرچم دستی 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

کد خروج	یادداشت ها
0	تمام آزمایشات اجرا شده قبول شد.
1	یک شکست کلی رخ داد. دلایل احتمالی عبارتند از: نام فایلی که وجود ندارد یا خطای HTTP/شبکه.
2	آزمایش خارج شد زیرا دستورات یا آرگومان های ناشناخته ارائه شد.
10	یک یا چند مورد تست (کلاس‌های آزمایش شده یا روش‌های کلاس) در یک اجرای آزمایشی موفق نشدند.
15	به دلیل یک خطای غیرمنتظره، Firebase Test Lab نتوانست تشخیص دهد که آیا ماتریس آزمایش موفق شد یا ناموفق.
18	محیط تست برای اجرای این تست به دلیل ابعاد تست ناسازگار پشتیبانی نمی شود. اگر سطح API انتخاب شده Android توسط نوع دستگاه انتخاب شده پشتیبانی نشود، ممکن است این خطا رخ دهد.
19	ماتریس تست توسط کاربر لغو شد.
20	یک خطای زیرساخت آزمایشی رخ داد.