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

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

عند إنشاء تطبيقك باستخدام نظام التصميم Gradle، يتيح لك المكوّن الإضافي لنظام Gradle المتوافق مع Android إجراء الاختبارات من مشروع Gradle باستخدام سطر الأوامر. للحصول على تحكّم أكثر دقة، يمكنك اختيار إجراء اختباراتك من خلال 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)، تتوفّر خيارات أكثر لاختيار الاختبارات التي سيتم تنفيذها مقارنةً بأي طريقة أخرى. يمكنك اختيار طرق اختبار فردية أو فلترة الاختبارات وفقًا لتعليق توضيحي مخصّص أو تحديد خيارات الاختبار. بما أنّ عملية التشغيل التجريبي يتم التحكّم فيها بالكامل من سطر الأوامر، يمكنك تخصيص الاختبار باستخدام نصوص برمجية shell بطرق مختلفة.

لتشغيل اختبار من سطر الأوامر، شغِّل adb shell لبدء واجهة سطر الأوامر على جهازك أو المحاكي. داخل هذا البرنامج، يمكنك التفاعل مع مدير الأنشطة باستخدام الأمر am واستخدام الأمر الفرعي instrument لتشغيل اختباراتك.

كاختصار، يمكنك بدء adb shell، واستدعاء 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 instrument flags

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

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

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

am instrument options

تنقل الأداة 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 جميع الاختبارات في الحزمة وسيتجاهل مفتاح الفئة.
يستبعد كلّ من المفتاح 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/`