این راهنما نحوه اجرای تست Instrumentation، Robo یا Game Loop را با استفاده از رابط خط فرمان gcloud شرح می‌دهد.
برای مشاهده لیست کاملی از دستورات gcloud که می‌توانید با برنامه اندروید خود در Test Lab استفاده کنید، به مستندات مرجع برای gcloud firebase test android مراجعه کنید.
قبل از اینکه شروع کنی
اگر هنوز Firebase را به پروژه اندروید خود اضافه نکرده‌اید، آن را اضافه کنید.
مرحله ۱. تنظیمات رابط خط فرمان gcloud
- دانلود SDK گوگل کلود
- مطمئن شوید که نصب شما به‌روز است:
gcloud components update
- با استفاده از حساب گوگل خود وارد رابط خط فرمان gcloud شوید:
gcloud auth login
- پروژه Firebase خود را در gcloud تنظیم کنید، که در آن PROJECT_ID شناسه پروژه Firebase شما است:
gcloud config set project PROJECT_ID
این شامل ابزار gcloud CLI نیز می‌شود.
مرحله ۲. دستگاه‌های تست موجود را بررسی کنید
برای مشاهده دستگاه‌های تست و محلی که برای تست شما در دسترس هستند، از دستورات gcloud زیر استفاده کنید.
به عنوان یک گزینه، می‌توانید برنامه Notepad نمونه را نیز دانلود کنید تا بلافاصله اجرای دستورات را شروع کنید. از فایل باینری app-debug-unaligned.apk و فایل تست‌های ابزار دقیق app-debug-test-unaligned.apk که در NotePad/app/build/outputs/apk/ قرار دارند، استفاده کنید.
models list: فهرستی از دستگاه‌های اندروید موجود برای آزمایش روی آنها را دریافت کنید.gcloud firebase test android models listدر خروجی دستور:
- ستون
MODEL_IDشامل شناسه‌ای است که می‌توانید بعداً برای اجرای تست‌ها روی مدل دستگاه از آن استفاده کنید. - ستون
OS_VERSION_IDشامل نسخه‌های سیستم عامل پشتیبانی شده توسط دستگاه است.
خروجی مثال
- ستون
models describe: اطلاعات بیشتری در مورد یکMODEL_IDخاص اندروید دریافت کنید.gcloud firebase test android models describe MODEL_IDخروجی شامل نام تجاری مدل دستگاه، سازنده، نسخه‌های سیستم عامل، سطوح API پشتیبانی شده، رابط‌های دودویی برنامه (ABI) پشتیبانی شده، تاریخ انتشار و اینکه آیا دستگاه فیزیکی است یا مجازی، می‌شود.
versions list: فهرستی از نسخه‌های سیستم عامل موجود برای آزمایش را دریافت کنید.gcloud firebase test android versions listشما می‌توانید از شناسه‌ی هر یک از دو ستون اول خروجی دستور (
OS_VERSION_IDوVERSION) برای اجرای تست‌ها در آینده روی یک نسخه از سیستم عامل اندروید استفاده کنید. اگر نسخه‌های سیستم عامل اندروید مورد نظر برای تست را مشخص نکنید، از پیش‌فرض ذکر شده در زیر ستونTAGSاستفاده می‌شود.خروجی مثال
locales list: لیست فعلی زبان‌های موجود برای آزمایش را دریافت کنید.gcloud firebase test android versions listستون اول خروجی دستور،
LOCALE، شامل شناسه‌ای است که می‌توانید بعداً برای اجرای تست‌ها روی یک زبان محلی از آن استفاده کنید. اگر زبان‌های محلی را برای تست مشخص نکنید، زبان انگلیسی به عنوان زبان محلی پیش‌فرض استفاده می‌شود.
مرحله ۳. آزمون خود را اجرا کنید
اکنون که طیف مدل‌های دستگاه، زبان‌های محلی و نسخه‌های سیستم عامل موجود برای آزمایش برنامه خود را می‌دانید، می‌توانید دستگاه‌ها را با استفاده از دستور gcloud firebase test android run و پرچم --device برای اجرای تست‌های Robo یا instrumentation مشخص کنید.
یک تست 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 روی پیکربندی‌های مشخص شده دستگاه اندروید خود استفاده کنید. از نوع تست 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"
- پارامتر instrumentation
--typeدر صورتی که یک APK آزمایشی با--testمشخص شده باشد، ضمنی است. - برای کمک به شناسایی و مکان‌یابی ماتریس‌های آزمایشی خود در کنسول Firebase ، می‌توانید از پرچم اختیاری
--client-details matrixLabel="Example matrix label"برای برچسب‌گذاری ماتریس آزمایشی خود استفاده کنید. - شما می‌توانید مجموعه کامل گزینه‌های خط فرمان برای اجرای تست‌ها را با تایپ کردن
gcloud help firebase test android runمشاهده کنید.
به عنوان جایگزینی برای مشخص کردن این آرگومان‌ها در خط فرمان، می‌توانید به صورت اختیاری آرگومان‌های خود را در یک فایل آرگومان با فرمت YAML مشخص کنید. برای یادگیری نحوه استفاده از این ویژگی، gcloud topic arg-files اجرا کنید.
رابط خط فرمان gcloud از Android Test Orchestrator پشتیبانی می‌کند. Orchestrator به AndroidJUnitRunner نسخه ۱.۱ یا بالاتر نیاز دارد. برای فعال کردن آن، gcloud firebase test android run با دستور زیر استفاده کنید:
پرچم --use-orchestrator . برای غیرفعال کردن آن از پرچم --no-use-orchestrator استفاده کنید.
شما همچنین می‌توانید نحوه اجرای تست‌های ابزار دقیق خود را Test Lab با استفاده از پرچم‌های اضافی که در بالا نشان داده نشده‌اند، کنترل کنید. به عنوان مثال، می‌توانید از پرچم --test-targets برای آزمایش یک کلاس یا یک متد کلاس که توسط APK تست شما استفاده می‌شود، استفاده کنید. همچنین می‌توانید با استفاده از پرچم --num-flaky-test-attempts بفهمید که آیا تست ناموفق شما واقعاً flaky بوده است یا خیر، که تعداد دفعاتی را که یک تست باید دوباره امتحان شود در صورتی که یک یا چند مورد از موارد تست آن به هر دلیلی شکست بخورد، مشخص می‌کند. برای کسب اطلاعات بیشتر، به 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 پیدا کنید:
- لینک کنسول Firebase را که ابزار
gcloudبالای جدول نتایج آزمایش در ترمینال شما چاپ کرده است، باز کنید. - برای باز کردن صفحه جزئیات آن اجرا، روی یک اجرای آزمایشی از لیست موجود در آن لینک کلیک کنید.
- برای رفتن به بخش Cloud Storage حاوی نتایج آزمایش آن اجرا، روی نتایج آزمایش کلیک کنید.
- برای مشاهده گزارش پوشش کد خود
artifacts/coverage.ecباز کنید.
نتایج آزمون خود را تحلیل کنید
پس از چند دقیقه، خلاصه‌ای از نتایج آزمایش شما توسط ابزار gcloud چاپ می‌شود:
خروجی اجرای تست خط فرمان شما همچنین شامل پیوندی برای مشاهده نتایج تست است. برای کسب اطلاعات بیشتر در مورد نحوه تفسیر این نتایج، به تجزیه و تحلیل Firebase Test Lab برای نتایج اندروید مراجعه کنید.
ورود سفارشی و ورودی متن با تست Robo
Robo test به طور خودکار صفحات ورود به سیستمی را که از حساب گوگل برای احراز هویت استفاده می‌کنند، تکمیل می‌کند، مگر اینکه از پارامتر --no-auto-google-login استفاده کنید. همچنین می‌تواند صفحات ورود به سیستم سفارشی را با استفاده از اعتبارنامه‌های حساب آزمایشی که ارائه می‌دهید، تکمیل کند. همچنین می‌توانید از این پارامتر برای ارائه متن ورودی سفارشی برای سایر فیلدهای متنی مورد استفاده برنامه خود استفاده کنید.
برای تکمیل فیلدهای متنی در برنامه خود، از پارامتر --robo-directives استفاده کنید و لیستی از جفت‌های key-value که با کاما از هم جدا شده‌اند، ارائه دهید، که در آن key ، نام منبع اندروید عنصر رابط کاربری هدف و value رشته متنی است. همچنین می‌توانید از این پرچم برای گفتن به Robo استفاده کنید تا عناصر رابط کاربری خاصی (مثلاً دکمه "خروج") را نادیده بگیرد. فیلدهای EditText پشتیبانی می‌شوند اما فیلدهای متنی در عناصر رابط کاربری WebView پشتیبانی نمی‌شوند.
برای مثال، می‌توانید از پارامتر زیر برای ورود سفارشی استفاده کنید:
--robo-directives username_resource=username,password_resource=password
دستورات و پرچم‌های موجود
رابط خط فرمان (CLI) Test Lab gcloud چندین دستور و فلگ (flag) در دسترس دارد که به شما امکان می‌دهد تست‌هایی با مشخصات مختلف اجرا کنید:
پرچم Orchestrator تست اندروید : پرچمی برای فعال کردن Orchestrator، ابزاری که به شما امکان می‌دهد هر یک از تست‌های برنامه خود را در فراخوانی مستقل
Instrumentationاجرا کنید. Test Lab همیشه آخرین نسخه Orchestrator را اجرا می‌کند.پرچم‌های تست حلقه بازی : مجموعه‌ای از پرچم‌های پیکربندی که یک «حالت آزمایشی» را برای شبیه‌سازی اقدامات بازیکن در برنامه‌های بازی فعال و کنترل می‌کنند. درباره اجرای تست‌های حلقه بازی با Test Lab بیشتر بیاموزید.
پرچم Uniform Sharding (در نسخه بتا) : پرچمی که تعداد Shardهایی را که می‌خواهید موارد آزمایشی را به طور مساوی در آنها توزیع کنید، مشخص می‌کند. Shardها به صورت موازی روی دستگاه‌های جداگانه اجرا می‌شوند.
پرچم شاردینگ دستی (در نسخه بتا) : پرچمی که گروهی از بسته‌ها، کلاس‌ها و/یا موارد آزمایشی را برای اجرا در یک شارد (گروهی از موارد آزمایشی) مشخص می‌کند. شاردها به صورت موازی روی دستگاه‌های جداگانه اجرا می‌شوند.
پرچم پروفایل‌های ترافیک شبکه (در نسخه بتا) : پرچمی که مشخص می‌کند تست‌های شما با دستگاه‌های فیزیکی از کدام پروفایل شبکه استفاده می‌کنند. پروفایل‌های شبکه شرایط مختلف شبکه را شبیه‌سازی می‌کنند و به شما امکان می‌دهند عملکرد برنامه خود را در شبکه‌های غیرقابل اعتماد یا غیرقابل پیش‌بینی آزمایش کنید.
اسکریپت نویسی دستورات gcloud با Test Lab
شما می‌توانید از اسکریپت‌های shell یا فایل‌های batch برای خودکارسازی دستورات تست برنامه تلفن همراه استفاده کنید که در غیر این صورت با استفاده از خط فرمان gcloud اجرا می‌کردید. مثال زیر یک اسکریپت bash است که یک تست instrumentation را با یک timeout دو دقیقه‌ای اجرا می‌کند و در صورت موفقیت‌آمیز بودن اجرای تست، گزارش می‌دهد:
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 | تمام آزمایش‌های اجرا شده با موفقیت انجام شدند. |
| ۱ | یک خطای کلی رخ داده است. دلایل احتمالی عبارتند از: نام فایلی که وجود ندارد یا خطای HTTP/شبکه. |
| ۲ | آزمایش به دلیل ارائه دستورات یا آرگومان‌های ناشناخته، خاتمه یافت. |
| ۱۰ | یک یا چند مورد آزمایشی (کلاس‌ها یا متدهای کلاس آزمایش‌شده) در یک اجرای آزمایشی با موفقیت انجام نشد. |
| ۱۵ | Firebase Test Lab به دلیل یک خطای غیرمنتظره نتوانست تشخیص دهد که آیا ماتریس تست پذیرفته شده یا شکست خورده است. |
| ۱۸ | محیط تست برای اجرای این تست به دلیل ابعاد تست ناسازگار پشتیبانی نمی‌شود. این خطا ممکن است در صورتی رخ دهد که سطح API اندروید انتخاب شده توسط نوع دستگاه انتخاب شده پشتیبانی نشود. |
| ۱۹ | ماتریس آزمون توسط کاربر لغو شد. |
| ۲۰ | خطایی در زیرساخت آزمایشی رخ داده است. |