الاختبار من سطر الأوامر

يوضّح هذا المستند كيفية إجراء الاختبارات مباشرةً من سطر الأوامر. ويفترض هذا المستند أنّك تعرف كيفية إنشاء تطبيق Android و كتابة اختبارات له. لمزيد من المعلومات حول كيفية إنشاء اختبارات لتطبيقك، يُرجى الاطّلاع على مقالة اختبار التطبيقات على Android.

عند إنشاء تطبيقك باستخدام نظام التصميم Gradle، يتيح لك المكوّن الإضافي لنظام Gradle المتوافق مع Android Gradle إجراء الاختبارات من مشروع Gradle باستخدام سطر الأوامر. وللتحكّم بشكل أكثر دقة، يمكنك اختيار إجراء الاختبارات من خلال shell في Android Debug Bridge (adb). قد يكون ذلك مفيدًا عند إجراء الاختبارات في بيئة تكامل مستمر.

للتعرّف على كيفية إجراء اختبارات تلقائية لقياس حالة التطبيق من سطر الأوامر باستخدام الأجهزة الافتراضية التي يديرها Gradle، يُرجى الاطّلاع على مقالة توسيع نطاق الاختبارات باستخدام الأجهزة المُدارة من 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‏ 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 لبدء واجهة سطر أوامر على جهازك أو المحاكي. داخل هذه الواجهة، يمكنك التفاعل مع الـ activity manager باستخدام الأمر 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 هو قيمة السمة package لعنصر ملف البيان في ملف بيان حزمة الاختبار (AndroidManifest.xml).

فئة أداة إجراء اختبار Android هي عادةً AndroidJUnitRunner:
```
adb shell am instrument -w com.android.example/androidx.test.runner.AndroidJUnitRunner
```

تظهر نتائج الاختبار في STDOUT.

علامات am instrument

للعثور على قائمة بجميع العلامات التي يمكنك استخدامها مع الأمر am instrument، نفِّذ adb shell am help. يوضّح الجدول التالي بعض العلامات المهمة:

الجدول 2. علامات am instrument المهمة

الإبلاغ	القيمة	الوصف
`-w`	(لا شيء)	تفرض هذه العلامة على `am instrument` الانتظار إلى أن تنتهي أداة قياس حالة التطبيق قبل أن تنتهي بنفسها. ويؤدي ذلك إلى إبقاء الواجهة مفتوحة إلى أن تنتهي الاختبارات. هذه العلامة مطلوبة للاطّلاع على نتائج اختباراتك.
`-r`	(لا شيء)	تُخرج هذه العلامة النتائج بتنسيق أولي. استخدِم هذه العلامة عندما تريد جمع قياسات الأداء حتى لا يتم تنسيقها كنتائج اختبار. تم تصميم هذه العلامة لاستخدامها مع العلامة `-e perf true` (الموضّحة في قسم خيارات am instrument).
`-e`	`<test_options>`	توفّر هذه العلامة خيارات الاختبار كأزواج من المفاتيح والقيم. تُمرِّر الأداة `am instrument` هذه الخيارات إلى فئة أداة قياس حالة التطبيق المحدّدة باستخدام الطريقة `onCreate()`. يمكنك تحديد عدة مواضع للعلامة `-e <test_options>`. يوضّح قسم خيارات am instrument المفاتيح والقيم. يمكنك استخدام أزواج المفاتيح والقيم هذه مع `AndroidJUnitRunner` أو مع `InstrumentationTestRunner` وفئاته الفرعية فقط. لن يكون لاستخدامها مع أي فئة أخرى أي تأثير.
`--no-hidden-api-checks`	(لا شيء)	توقف هذه العلامة القيود المفروضة على استخدام واجهات برمجة التطبيقات المخفية. لمزيد من المعلومات حول واجهات برمجة التطبيقات المخفية وكيفية تأثيرها في تطبيقك، يُرجى قراءة مقالة القيود المفروضة على الواجهات غير التابعة لحزمة تطوير البرامج (SDK).

خيارات am instrument

تُمرِّر أداة am instrument خيارات الاختبار إلى AndroidJUnitRunner أو InstrumentationTestRunner في شكل أزواج من المفاتيح والقيم، باستخدام العلامة -e، مع هذه البنية:

-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

يسرد الجدول التالي أزواج المفاتيح والقيم التي يمكنك استخدامها مع أداة إجراء الاختبار:

الجدول 3. أزواج المفاتيح والقيم للعلامة -e التي يمكنك استخدامها مع أداة إجراء الاختبار

المفتاح	القيمة	الوصف
`package`	`<Java_package_name>`	اسم حزمة Java المؤهَّل بالكامل لإحدى الـ حِزم في تطبيق الاختبار. يتم تنفيذ أي فئة من فئات حالات الاختبار تستخدم اسم الحزمة هذا. يُرجى العِلم أنّ هذا ليس اسم حزمة Android، إذ إنّ حزمة الاختبار لها اسم حزمة Android واحد ولكن قد تحتوي على عدة حِزم Java بداخلها.
`class`	`<class_name>`	اسم فئة Java المؤهَّل بالكامل لإحدى فئات حالات الاختبار. يتم تنفيذ فئة حالة الاختبار هذه فقط.
`class`	`<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`
`coverageFile`	`<filename>`	تتجاوز هذه العلامة الموقع التلقائي لملف تغطية EMMA على الجهاز. حدِّد هذه القيمة كمسار واسم ملف بتنسيق UNIX. يوضّح الإدخال الخاص بالمفتاح `emma` اسم الملف التلقائي.

عند استخدام العلامة -e، يُرجى مراعاة ما يلي:

am instrument يستدعي onCreate(Bundle) مع Bundle يحتوي على أزواج المفاتيح والقيم.
تحظى العلامة package بالأولوية على العلامة class. إذا حدّدت حزمة ثم حدّدت بشكل منفصل فئة ضمن هذه الحزمة، يُجري Android جميع الاختبارات في الحزمة ويتجاهل العلامة `class`.
يستبعد كلٌّ من العلامتين 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 مرجع واجهة برمجة التطبيقات.

عرض تقارير الاختبار الموحّدة

يوفّر المكوّن الإضافي لنظام Gradle المتوافق مع Android مهام تقارير الاختبار الموحّدة، التي تُنشئ لوحات بيانات بتنسيق HTML تدمج نتائج اختبارات الوحدة واختبارات قياس حالة التطبيق.

المتطلبات الأساسية

الإصدار 9.2.0-alpha07 أو إصدار أحدث من المكوّن الإضافي لنظام Gradle المتوافق مع Android

لإنشاء تقارير اختبار موحّدة، نفِّذ إحدى المهام التالية:

نطاق التقرير	الأمر	الوصف	موقع التقرير
الوحدة الحالية	`./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/`