از خط فرمان تست کنید

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

وقتی برنامه خود را با استفاده از سیستم ساخت Gradle می‌سازید، افزونه Android Gradle به شما امکان می‌دهد تست‌ها را از پروژه Gradle خود با استفاده از خط فرمان اجرا کنید. برای کنترل دقیق‌تر، می‌توانید تست‌های خود را از طریق پوسته Android Debug Bridge (adb) اجرا کنید. این می‌تواند هنگام اجرای تست‌ها در یک محیط ادغام مداوم مفید باشد.

برای یادگیری نحوه اجرای تست‌های خودکارِ ابزار دقیق از خط فرمان با استفاده از دستگاه‌های مجازی که Gradle برای شما مدیریت می‌کند، به بخش «مقیاس‌بندی تست‌های خود با دستگاه‌های مدیریت‌شده Gradle» مراجعه کنید.

اجرای تست‌ها با Gradle

افزونه‌ی اندروید گریدل (Android Gradle) به شما امکان می‌دهد تا با استفاده از خط فرمان، تست‌هایی را از پروژه‌ی گریدل خود اجرا کنید.

جدول زیر نحوه اجرای تست‌های شما با Gradle را خلاصه می‌کند:

جدول 1. روش‌های مختلف اجرای تست‌ها با Gradle

نوع تست واحد دستور اجرا محل دریافت نتیجه آزمایش
تست واحد محلی اجرای وظیفه test : 

./gradlew test
فایل‌های نتیجه تست HTML:
path_to_your_project / module_name /build/reports/tests/ دایرکتوری.

فایل‌های نتیجه آزمایش XML:
path_to_your_project / module_name /build/test-results/ دایرکتوری.

آزمون واحد ابزار دقیق وظیفه connectedAndroidTest را اجرا کنید: 

./gradlew connectedAndroidTest
فایل‌های نتیجه تست HTML:
path_to_your_project / module_name /build/reports/androidTests/connected/ دایرکتوری.

فایل‌های نتیجه آزمایش XML:
path_to_your_project / module_name /build/outputs/androidTest-results/connected/ دایرکتوری.

Gradle از اختصارات نام وظیفه پشتیبانی می‌کند. برای مثال، می‌توانید وظیفه connectedAndroidTest را با وارد کردن دستور زیر آغاز کنید:

./gradlew cAT

همچنین می‌توانید Gradle tasks check و connectedCheck اجرا کنید. این taskها به ترتیب تست‌های محلی یا instrumented شما را اجرا می‌کنند، اما شامل بررسی‌های دیگری که توسط سایر افزونه‌های Gradle اضافه شده‌اند نیز می‌شوند.

اجرای تست‌ها روی یک ماژول

وظایف test و connectedAndroidTest تست‌ها را روی هر ماژول در پروژه شما اجرا می‌کنند. می‌توانید با قرار دادن نام ماژول و یک دونقطه (:) قبل از وظیفه test یا connectedAndroidTest ، تست‌ها را روی یک ماژول خاص اجرا کنید. برای مثال، دستور زیر تست‌های instrumented را فقط برای ماژول mylibrary اجرا می‌کند:

./gradlew mylibrary:connectedAndroidTest

اجرای تست‌ها روی یک نسخه ساخت‌یافته

وظایف test و connectedAndroidTest تست‌ها را روی هر build variant در پروژه شما اجرا می‌کنند. می‌توانید با استفاده از سینتکس زیر، یک build variant خاص را هدف قرار دهید:

  • برای تست‌های واحد محلی: 
    ./gradlew testVariantNameUnitTest
  • برای آزمایش‌های ابزار دقیق: 
    ./gradlew connectedVariantNameAndroidTest

اجرای متدها یا کلاس‌های تست خاص

هنگام اجرای تست‌های واحد محلی، Gradle به شما امکان می‌دهد با استفاده از پرچم --tests تست‌های خاصی را هدف قرار دهید. برای مثال، دستور زیر فقط تست‌های sampleTestMethod را برای نوع ساخت مشخص شده اجرا می‌کند. برای کسب اطلاعات بیشتر در مورد استفاده از پرچم --tests ، مستندات Gradle در مورد فیلتر کردن تست را مطالعه کنید.


./gradlew testVariantNameUnitTest --tests '*.sampleTestMethod'

اجرای تست‌ها با adb

وقتی تست‌ها را از خط فرمان با Android Debug Bridge (adb) اجرا می‌کنید، گزینه‌های بیشتری برای انتخاب تست‌ها برای اجرا نسبت به هر روش دیگری وجود دارد. می‌توانید متدهای تست جداگانه را انتخاب کنید، تست‌ها را بر اساس یک حاشیه‌نویسی سفارشی فیلتر کنید یا گزینه‌های تست را مشخص کنید. از آنجایی که اجرای تست کاملاً از خط فرمان کنترل می‌شود، می‌توانید تست خود را با اسکریپت‌های پوسته به روش‌های مختلف سفارشی کنید.

برای اجرای تست از خط فرمان، adb shell اجرا کنید تا یک پوسته خط فرمان روی دستگاه یا شبیه‌ساز شما شروع شود. در داخل آن پوسته می‌توانید با استفاده از دستور am با activity manager تعامل داشته باشید و از زیردستور instrument آن برای اجرای تست‌های خود استفاده کنید.

به عنوان یک میانبر، می‌توانید یک پوسته adb را اجرا کنید، am instrument را فراخوانی کنید و پرچم‌های خط فرمان را در یک خط ورودی مشخص کنید. پوسته روی دستگاه یا شبیه‌ساز باز می‌شود، تست‌های شما را اجرا می‌کند، خروجی تولید می‌کند و سپس به خط فرمان روی رایانه شما باز می‌گردد.

برای اجرای تست با am instrument :

  1. برنامه اصلی خود را بسازید یا بازسازی کنید و بسته آزمایشی را آزمایش کنید.
  2. بسته آزمایشی و فایل‌های بسته اندروید برنامه اصلی (فایل‌های APK) را روی دستگاه اندروید یا شبیه‌ساز فعلی خود نصب کنید .

  3. در خط فرمان، وارد کنید:

    adb shell am instrument -w <test_package_name>/<runner_class>

    که در آن <test_package_name> نام پکیج اندروید اپلیکیشن آزمایشی شما و <runner_class> نام کلاس اجراکننده تست اندروید مورد استفاده شماست. نام پکیج اندروید، مقدار ویژگی package عنصر manifest در فایل manifest پکیج آزمایشی شما ( AndroidManifest.xml ) است.

    کلاس اجراکننده تست اندروید معمولاً AndroidJUnitRunner است:

    adb shell am instrument -w com.android.example/androidx.test.runner.AndroidJUnitRunner

نتایج آزمایش شما در STDOUT ظاهر می‌شود.

پرچم‌های ابزار دقیق AM

برای یافتن لیستی از تمام پرچم‌های مورد استفاده با دستور am instrument ، adb shell am help را اجرا کنید. برخی از پرچم‌های مهم در جدول زیر شرح داده شده‌اند:

جدول 2. پرچم‌های مهم am instrument

پرچم ارزش توضیحات
-w (هیچکدام) am instrument تا پایان عملیات ابزار دقیق منتظر بماند و سپس خودش را خاتمه دهد. این کار باعث می‌شود پوسته تا پایان آزمایش‌ها باز بماند. این پرچم برای مشاهده نتایج آزمایش‌های شما لازم است.
-r (هیچکدام) نتایج را در قالب خام خروجی می‌دهد. از این پرچم زمانی استفاده کنید که می‌خواهید اندازه‌گیری‌های عملکرد را جمع‌آوری کنید تا به عنوان نتایج آزمون قالب‌بندی نشوند. این پرچم برای استفاده با پرچم -e perf true (که در بخش گزینه‌های ابزار am مستند شده است) طراحی شده است.
-e <test_options> گزینه‌های تست را به صورت جفت‌های کلید-مقدار ارائه می‌دهد. ابزار am instrument این موارد را با استفاده از متد onCreate() به کلاس instrumentation مشخص شده ارسال می‌کند. می‌توانید چندین مورد از -e <test_options> را مشخص کنید. کلیدها و مقادیر در بخش گزینه‌های am instrumentation شرح داده شده‌اند. شما فقط می‌توانید از این جفت‌های کلید-مقدار با AndroidJUnitRunner یا با InstrumentationTestRunner و زیرکلاس‌های آن استفاده کنید. استفاده از آنها با هر کلاس دیگری هیچ تاثیری ندارد.
--no-hidden-api-checks (هیچکدام) محدودیت‌های استفاده از APIهای پنهان را غیرفعال می‌کند. برای اطلاعات بیشتر در مورد اینکه APIهای پنهان چه هستند و چگونه می‌توانند بر برنامه شما تأثیر بگذارند، بخش «محدودیت‌ها در رابط‌های غیر SDK» را مطالعه کنید.

گزینه‌های ابزار دقیق

ابزار 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> نام کامل بسته جاوا برای یکی از بسته‌های موجود در برنامه آزمایشی. هر کلاس مورد آزمایشی که از این نام بسته استفاده کند، اجرا می‌شود. توجه داشته باشید که این نام، نام بسته اندروید نیست؛ یک بسته آزمایشی دارای یک نام بسته اندروید است اما ممکن است چندین بسته جاوا درون خود داشته باشد.
class <class_name> نام کلاس جاوای کامل برای یکی از کلاس‌های مورد آزمایشی. فقط این کلاس مورد آزمایشی اجرا می‌شود.
<class_name> # method name نام یک کلاس مورد آزمایشی کاملاً واجد شرایط و یکی از متدهای آن. فقط این متد اجرا می‌شود. به علامت # بین نام کلاس و نام متد توجه کنید.
func true تمام کلاس‌های تستی که InstrumentationTestCase ارث‌بری می‌کنند را اجرا می‌کند.
unit true تمام کلاس‌های تستی را که از InstrumentationTestCase یا PerformanceTestCase ارث‌بری نمی‌کنند ، اجرا می‌کند.
size [ small | medium ​​| large ] یک متد تست را اجرا می‌کند که بر اساس اندازه حاشیه‌نویسی شده است. این حاشیه‌نویسی‌ها عبارتند از @SmallTest ، @MediumTest و @LargeTest .
perf true تمام کلاس‌های آزمایشی که PerformanceTestCase پیاده‌سازی می‌کنند، اجرا می‌کند. هنگام استفاده از این گزینه، پرچم -r را برای am instrument مشخص کنید تا خروجی در قالب خام نگه داشته شود و به عنوان نتایج آزمایش دوباره قالب‌بندی نشود.
debug true تست‌ها را در حالت اشکال‌زدایی اجرا می‌کند.
log true تمام تست‌های مشخص شده را بارگذاری و ثبت می‌کند اما آنها را اجرا نمی‌کند. اطلاعات تست در STDOUT ظاهر می‌شود. از این برای تأیید ترکیب سایر فیلترها و مشخصات تست استفاده کنید.
emma true یک تحلیل پوشش کد EMMA را اجرا می‌کند و خروجی را در /data/<app_package>/coverage.ec روی دستگاه می‌نویسد. برای لغو محل فایل، از کلید coverageFile که در ورودی زیر توضیح داده شده است، استفاده کنید.

توجه: این گزینه نیاز به یک نسخه آزمایشی از برنامه کاربردی تحت ابزار EMMA دارد که می‌توانید آن را با هدف coverage target) تولید کنید.

coverageFile <filename> مکان پیش‌فرض فایل پوشش EMMA روی دستگاه را لغو می‌کند. این مقدار را به عنوان مسیر و نام فایل در قالب UNIX مشخص کنید. نام فایل پیش‌فرض در ورودی مربوط به کلید emma توضیح داده شده است.

هنگام استفاده از آپشن -e ، به موارد زیر توجه داشته باشید:

  • am instrument تابع onCreate(Bundle) با یک Bundle حاوی جفت‌های کلید-مقدار فراخوانی می‌کند.
  • کلید package بر کلید class اولویت دارد. اگر یک بسته را مشخص کنید و سپس به طور جداگانه یک کلاس را در آن بسته مشخص کنید، اندروید تمام تست‌های موجود در بسته را اجرا می‌کند و کلید کلاس را نادیده می‌گیرد.
  • کلید func و کلید unit متقابلاً منحصر به فرد هستند.

مثال‌های کاربرد

بخش‌های زیر نمونه‌هایی از استفاده از am instrument برای اجرای تست‌ها را ارائه می‌دهند. این نمونه‌ها بر اساس ساختار زیر هستند:

  • نام بسته‌ی آزمایشی اندروید 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

اجرای تمام تست‌ها در یک کلاس Test Case

برای اجرای تمام تست‌های موجود در کلاس 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

می‌توانید موارد استفاده بیشتری را در مرجع API AndroidJUnitRunner بیابید.

مشاهده گزارش‌های تست یکپارچه

افزونه‌ی اندروید Gradle وظایف گزارش تست یکپارچه‌ای را ارائه می‌دهد که داشبوردهای HTML تولید می‌کنند و نتایج حاصل از تست‌های واحد و Instrumented را ادغام می‌کنند.

پیش‌نیازها

  • افزونه‌ی گریدل اندروید نسخه ۹.۲.۰-alpha07 یا بالاتر.

برای تولید گزارش‌های تست یکپارچه، یکی از وظایف زیر را اجرا کنید:

دامنه گزارش فرماندهی توضیحات گزارش موقعیت مکانی
ماژول فعلی ./gradlew : module_name :createTestReport یک گزارش تست یکپارچه برای ماژول فعلی تولید می‌کند که نتایج تست واحد و ابزار دقیق را ادغام می‌کند. path_to_your_project / module_name /build/reports/tests/test-report/
ماژول فعلی و وابستگی‌ها ./gradlew : module_name :createAggregatedTestReport یک گزارش تست یکپارچه برای ماژول برنامه فعلی و وابستگی‌های کتابخانه آن تولید می‌کند. path_to_your_project / module_name /build/reports/tests/aggregated-test-report/