این سند نحوه اجرای آزمایش‌ها را مستقیماً از خط فرمان شرح می‌دهد. این سند فرض می‌کند که ازقبل با نحوه ایجاد برنامه Android و نوشتن آزمایش برای برنامه‌تان آشنا هستید. برای کسب اطلاعات بیشتر درباره نحوه ساختن آزمایش برای برنامه‌تان، به آزمایش کردن برنامه‌ها در Android مراجعه کنید.
ابزارهای خط فرمان و وظایف Gradle که در این صفحه توضیح داده شده است مستقل از جعبه‌ابزار رابط کاربری هستند. اگر می‌خواهید آزمون‌های میانای کاربر برای Compose بنویسید، به آزمون کردن چیدمان Compose مراجعه کنید. پس‌از اینکه آزمون‌هایتان را نوشتید، با این راهنما ادامه دهید تا آن‌ها را از پایانه یا محیط یکپارچه‌سازی مداوم ازراه‌دور اجرا کنید.
وقتی برنامه‌تان را بااستفاده از سیستم ساخت Gradle می‌سازید، افزایه Android Gradle به شما امکان می‌دهد آزمایش‌ها را از پروژه Gradle بااستفاده از خط فرمان اجرا کنید. برای کنترل دقیق‌تر، می‌توانید انتخاب کنید که آزمایش‌هایتان را ازطریق پوسته پل اشکال‌زدایی Android (adb) اجرا کنید. این کار می‌تواند هنگام اجرای آزمایش‌ها در محیط ادغام مداوم مفید باشد.
برای آشنایی با نحوه اجرای آزمایش‌های ابزاری خودکارشده از خط فرمان بااستفاده از دستگاه‌های مجازی که Gradle برای شما مدیریت می‌کند، به مقیاس‌بندی آزمایش‌ها با «دستگاه‌های تحت مدیریت Gradle» مراجعه کنید.
اجرای آزمایش‌ها با Gradle
افزایه Android Gradle به شما امکان می‌دهد بااستفاده از خط فرمان، آزمایش‌ها را از پروژه Gradle خود اجرا کنید.
جدول زیر نحوه اجرای آزمایش‌ها با Gradle را خلاصه می‌کند:
جدول ۱. روش‌های مختلف برای اجرای آزمایش‌ها با Gradle
| نوع آزمون واحد | فرمان اجرا | مکان نتیجه آزمایش |
|---|---|---|
| آزمون واحد محلی |
اجرای تکلیف test:
|
فایل‌های نتایج آزمایش HTML:path_to_your_project/module_name/build/reports/tests/
دایرکتوری.
فایل‌های نتایج آزمایش XML: |
| آزمون واحد ابزاردار |
تکلیف connectedAndroidTest را اجرا کنید:
|
فایل‌های نتایج آزمایش HTML:path_to_your_project/module_name/build/reports/androidTests/connected/
دایرکتوری.
فایل‌های نتایج آزمایش XML: |
Gradle از
اختصارهای نام تکلیف پشتیبانی می‌کند.
برای مثال، می‌توانید با وارد کردن فرمان زیر، تکلیف connectedAndroidTest را شروع کنید:
./gradlew cATهمچنین می‌توانید انتخاب کنید که تکالیف Gradle check و connectedCheck اجرا شوند. این
تکلیف‌ها به‌ترتیب آزمایش‌های محلی یا ابزاری شما را اجرا می‌کنند، اما
شامل بررسی‌های دیگری هستند که توسط افزایه‌های دیگر Gradle اضافه شده‌اند.
اجرای آزمایش‌ها روی واحد
تکالیف test و connectedAndroidTest آزمایش‌هایی را روی هر واحد در
پروژه شما اجرا می‌کنند. با پیشوند کردن تکلیف test یا connectedAndroidTest با نام واحد و دونقطه (:)، می‌توانید روی واحد خاصی آزمایش اجرا کنید. برای مثال، فرمان زیر آزمایش‌های ابزاری را فقط برای واحد mylibrary اجرا می‌کند:
./gradlew mylibrary:connectedAndroidTestاجرای آزمایش‌ها روی گونه ساخت
تکلیف‌های test و connectedAndroidTest آزمایش‌ها را روی هر
تنوع ساخت در پروژه‌تان اجرا می‌کنند. بااستفاده از دستورگان زیر می‌توانید
گونه ساخت خاصی را هدف‌یابی کنید:
- برای آزمون‌های واحد محلی:
./gradlew testVariantNameUnitTest - برای آزمایش‌های ابزاردار:
./gradlew connectedVariantNameAndroidTest
اجرای روش‌ها یا کلاس‌های آزمایشی خاص
هنگام اجرای آزمون‌های واحد محلی، Gradle به شما امکان می‌دهد آزمون‌های خاصی را بااستفاده از پرچم --tests هدف‌یابی کنید. برای مثال، فرمان زیر فقط آزمایش‌های
sampleTestMethod را برای تنوع ساخت مشخص‌شده اجرا می‌کند. برای کسب اطلاعات بیشتر درباره
استفاده از پرچم --tests، سند Gradle را درباره
فیلتر کردن آزمایش بخوانید.
./gradlew testVariantNameUnitTest --tests '*.sampleTestMethod'
اجرای آزمایش‌ها با adb
وقتی آزمایش‌ها را از خط فرمان با Android Debug Bridge (adb) اجرا می‌کنید، گزینه‌های بیشتری برای انتخاب آزمایش‌ها برای اجرا نسبت به هر روش دیگری وجود دارد. می‌توانید روش‌های آزمایش تکی را انتخاب کنید، آزمایش‌ها را براساس گزارمان سفارشی فیلتر کنید، یا گزینه‌های آزمایش را مشخص کنید. ازآنجایی‌که اجرای آزمایش کاملاً از خط فرمان کنترل می‌شود، می‌توانید آزمایش خود را با اسکریپت‌های پوسته به روش‌های مختلف سفارشی‌سازی کنید.
برای اجرای آزمایش از خط فرمان، adb shell را اجرا کنید تا پوسته خط فرمان در دستگاه یا شبیه‌سازتان شروع شود. در آن پوسته می‌توانید بااستفاده از فرمان am با
مدیر فعالیت
تعامل برقرار کنید و از فرمان فرعی instrument آن برای اجرای آزمایش‌هایتان استفاده کنید.
به‌عنوان میان‌بر، می‌توانید پوسته adb را شروع کنید، am instrument را فراخوانی کنید، و پرچم‌های خط فرمان را در یک خط ورودی مشخص کنید. پوسته در دستگاه یا شبیه‌ساز باز می‌شود، آزمایش‌هایتان را اجرا می‌کند، خروجی تولید می‌کند، و سپس به خط فرمان در رایانه‌تان برمی‌گردد.
برای اجرای آزمایش با am instrument:
- برنامه اصلی و بسته آزمایشی را بسازید یا بازسازی کنید.
- بسته آزمایشی و فایل‌های بسته Android برنامه اصلی (فایل‌های APK) را در دستگاه یا شبیه‌ساز مجهز به Android فعلی‌تان نصب کنید.
در خط فرمان، این عبارت را وارد کنید:
adb shell am instrument -w <test_package_name>/<runner_class>که
<test_package_name>نام بسته Android برنامه آزمایشی شما است، و<runner_class>نام کلاس اجراکننده آزمایش Android است که استفاده می‌کنید. نام بسته Android مقدار مشخصه بسته عنصر مانیفست در فایل مانیفست بسته آزمایشی شما است (AndroidManifest.xml).کلاس اجراکننده آزمایش Android معمولاً
AndroidJUnitRunnerاست:adb shell am instrument -w com.android.example/androidx.test.runner.AndroidJUnitRunner
نتایج آزمایش شما در STDOUT نشان داده می‌شود.
پرچم‌های ابزارآرایی am
برای پیدا کردن فهرست همه پرچم‌هایی که باید با فرمان am instrument استفاده شود،
adb shell am help را اجرا کنید. برخی‌از پرچم‌های مهم در جدول زیر توضیح داده شده است:
جدول ۲. am instrument پرچم
مهم
| پرچم | مقدار | شرح |
|---|---|---|
-w
|
(هیچ‌کدام) |
am instrument را مجبور می‌کند تا زمانی که ابزار دقیق
به‌کار خود پایان دهد، منتظر بماند و سپس خود به‌کار خود پایان دهد. این کار باعث می‌شود پوسته تا زمانی که آزمایش‌ها تمام نشده‌اند باز بماند. این پرچم برای دیدن نتایج آزمایش‌هایتان لازم است.
|
-r
|
(هیچ‌کدام) |
نتایج را در قالب خام برونداد می‌کند. وقتی می‌خواهید اندازه‌گیری‌های عملکرد را جمع‌آوری کنید تا به‌عنوان نتایج آزمایش قالب‌بندی نشوند، از این پرچم استفاده کنید. این پرچم برای استفاده با پرچم
-e perf true (مستندشده در بخش
گزینه‌های ابزار am) طراحی شده است.
|
-e
|
<test_options>
|
گزینه‌های آزمایش را به‌صورت جفت کلید-مقدار ارائه می‌دهد. ابزار
am instrument این موارد را بااستفاده از روش
onCreate()
به کلاس ابزارسازی مشخص‌شده
منتقل می‌کند. می‌توانید چندین رخداد از
-e <test_options> را مشخص کنید. کلیدها و مقادیر در بخش گزینه‌های ابزار am شرح داده شده‌اند. فقط می‌توانید از این جفت‌های کلید-مقدار با
AndroidJUnitRunner استفاده کنید.
استفاده از آن‌ها با هر کلاس دیگری تأثیری ندارد.
|
--no-hidden-api-checks
|
(هیچ‌کدام) | محدودیت‌های استفاده از میاناهای برنامه‌سازی کاربردی پنهان را غیرفعال می‌کند. برای اطلاعات بیشتر درباره اینکه میاناهای برنامه‌سازی کاربردی پنهان چیست و چگونه می‌تواند بر برنامه شما تأثیر بگذارد، محدودیت‌های مربوط به واسط‌های غیر کیت توسعه نرم‌افزار را بخوانید. |
گزینه‌های ابزار am
ابزار am instrument گزینه‌های آزمایش را به‌صورت جفت‌های کلید-مقدار بااستفاده از پرچم -e با این نحو به AndroidJUnitRunner یا InstrumentationTestRunner ارسال می‌کند:
-e <key> <value>
برخی‌از کلیدها چندین مقدار را می‌پذیرند. چندین مقدار را در فهرستی جداشده با کاما مشخص می‌کنید. برای مثال، این فراخوانی از
AndroidJUnitRunner چندین مقدار برای کلید package ارائه می‌دهد:
adb shell am instrument -w -e package com.android.test.package1,com.android.test.package2 \
> com.android.test/androidx.test.runner.AndroidJUnitRunnerجدول زیر جفت‌های کلید-مقدار را که می‌توانید با دونده آزمایشی خود استفاده کنید فهرست می‌کند:
جدول ۳. جفت‌های کلید-مقدار پرچم -e برای استفاده با دونده آزمون شما
| کلید | مقدار | شرح |
|---|---|---|
package
|
<Java_package_name>
|
نام بسته Java کاملاً واجدشرایط برای یکی از بسته‌های برنامه آزمایشی. هر کلاس چارچوب تستی که از این نام بسته استفاده می‌کند اجرا می‌شود. توجه داشته باشید که این نام بسته Android نیست؛ بسته آزمایشی یک نام بسته Android دارد اما ممکن است چندین بسته Java در آن وجود داشته باشد. |
class |
<class_name> |
نام کلاس Java کاملاً واجدشرایط برای یکی از کلاس‌های مورد آزمون. فقط این کلاس چارچوب تست اجرا می‌شود. |
<class_name>#method name |
نام کلاس چارچوب تست کاملاً واجدشرایط و یکی از روش‌های آن. فقط این روش اجرا می‌شود. علامت درهم (#) بین نام کلاس و نام روش را یادداشت کنید. | |
size |
[small | medium | large]
|
روش آزمایشی را که با اندازه حاشیه‌نویسی شده است اجرا می‌کند. گزارمان‌ها عبارت‌اند از
@SmallTest، @MediumTest، و
@LargeTest.
|
debug |
true |
آزمایش‌ها را در حالت اشکال‌زدایی اجرا می‌کند. |
log |
true |
همه آزمایش‌های مشخص‌شده را بار می‌کند و ثبت می‌کند اما آن‌ها را اجرا نمی‌کند. اطلاعات آزمایش در STDOUT نشان داده می‌شود. از این برای درستی‌سنجی
ترکیب‌های فیلترهای دیگر و مشخصات آزمون استفاده کنید.
|
emma |
true |
تحلیل پوشش کد EMMA را اجرا می‌کند و خروجی را در
/data/<app_package>/coverage.ec در دستگاه می‌نویسد. برای
لغو کردن مکان فایل، از کلید coverageFile
که در ورودی زیر توضیح داده شده است استفاده کنید.
توجه: این گزینه به ساختار ابزاربندی‌شده با EMMA
برنامه آزمایشی نیاز دارد که می‌توانید آن را با
هدف |
coverageFile |
<filename> |
مکان پیش‌فرض فایل پوشش EMMA را در دستگاه لغو می‌کند. این مقدار را به‌عنوان مسیر و نام فایل در قالب UNIX مشخص کنید.
نام فایل پیش‌فرض در ورودی کلید
emma شرح داده شده است.
|
هنگام استفاده از پرچم -e، به موارد زیر توجه داشته باشید:
-
am instrumentباBundleحاوی جفت‌های کلید-مقدارonCreate(Bundle)را فرا می‌خواند. - کلید
packageبر کلیدclassاولویت دارد. اگر بسته‌ای را مشخص کنید و سپس به‌طور جداگانه کلاسی را در آن بسته مشخص کنید، Android همه آزمایش‌ها را در بسته اجرا می‌کند و کلید کلاس را نادیده می‌گیرد. - کلید
funcو کلیدunitبه‌صورت متقابل انحصاری‌اند.
مثال‌هایی از کاربرد
بخش‌های زیر نمونه‌هایی از استفاده از am instrument برای اجرای آزمایش‌ها را ارائه می‌دهند.
این‌ها براساس ساختار زیر هستند:
- بسته آزمایشی نام بسته Android
com.android.demo.app.testsرا دارد. - دو کلاس آزمایش ابزاری:
TestClass1، که حاوی روش آزمایشیtestMethod1است.-
TestClass2، که حاوی روش‌های آزمایشیtestMethod2وtestMethod3است.
- اجراکننده آزمایش
AndroidJUnitRunnerاست.
اجرای کل بسته آزمایشی
برای اجرای همه کلاس‌های آزمایشی در بسته آزمایشی، این را وارد کنید:
adb shell am instrument -w com.android.demo.app.tests/androidx.test.runner.AndroidJUnitRunnerاجرای همه آزمایش‌ها در کلاس چارچوب تست
برای اجرای همه آزمایش‌ها در کلاس TestClass1، این را وارد کنید:
adb shell am instrument -w \
> -e class com.android.demo.app.tests.TestClass1 \
> com.android.demo.app.tests/androidx.test.runner.AndroidJUnitRunnerزیرمجموعه‌ای از آزمایش‌ها را انتخاب کنید
برای اجرای همه آزمایش‌ها در کلاس TestClass1 و روش testMethod3
در TestClass2، این را وارد کنید:
adb shell am instrument -w \
> -e class com.android.demo.app.tests.TestClass1,com.android.demo.app.tests.TestClass2#testMethod3 \
> com.android.demo.app.tests/androidx.test.runner.AndroidJUnitRunnerمی‌توانید موارد استفاده بیشتری را در
AndroidJUnitRunner
مرجع میانای برنامه‌سازی کاربردی پیدا کنید.
مشاهده گزارش‌های آزمایش یکپارچه
«افزایه Android Gradle» وظایف آزمایشی یکپارچه‌ای ارائه می‌دهد که داشبوردهای HTML تولید می‌کنند و نتایج آزمون‌های واحد و ابزاری را ادغام می‌کنند.
پیش‌نیازها
- افزایه Android Gradle نسخه 9.5.0-alpha05 یا بالاتر.
برای آزمایش کردن همه مجموعه‌های آزمایش، یکی از تکلیف‌های زیر را اجرا کنید:
| محدوده گزارش | فرمان | شرح | گزارش مکان |
|---|---|---|---|
| واحد کنونی | ./gradlew :module_name:testAllSuites --continue |
گزارش آزمون یکپارچه‌ای برای ماژول فعلی تولید می‌کند و نتایج آزمون واحد و ابزاری را ادغام می‌کند. | path_to_your_project/module_name/build/reports/testAllSuites/test-report/ |
| واحد کنونی و وابستگی‌ها | ./gradlew :module_name:testAllSuitesWithDependencies --continue |
گزارش آزمون یکپارچه‌ای برای واحد فعلی و وابستگی‌های کتابخانه آن تولید می‌کند و نتایج آزمون واحد و ابزاردار را ادغام می‌کند. | path_to_your_project/module_name/build/reports/testAllSuitesWithDependencies/test-report/ |