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

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

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

عند إنشاء تطبيقك باستخدام نظام التصميم 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/ directory.

ملفات نتائج اختبار XML:
path_to_your_project/module_name/build/test-results/ دليل

اختبار الوحدة الذي يتطلّب أدوات نفِّذ المهمة connectedAndroidTest: 

./gradlew connectedAndroidTest
ملفات نتائج اختبار HTML:
path_to_your_project/module_name/build/reports/androidTests/connected/ directory.

ملفات نتائج اختبار 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، اتّبِع الخطوات التالية:

  1. أنشئ أو أعد إنشاء تطبيقك الرئيسي وحزمة الاختبار.
  2. ثبِّت حزمة الاختبار وملفات حزمة تطبيق Android الرئيسية (ملفات APK) على جهاز Android الحالي أو المحاكي.

  3. في سطر الأوامر، أدخِل:

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

لاختبار جميع مجموعات الاختبار، شغِّل إحدى المهام التالية:

نطاق التقرير الأمر الوصف تقرير الموقع الجغرافي
الوحدة الحالية ./gradlew :module_name:testAllSuites تُنشئ تقرير اختبار موحّدًا للوحدة الحالية، وتدمج نتائج اختبارات الوحدة والاختبارات المبرمَجة. path_to_your_project/module_name/build/reports/tests/test-report/
الوحدة الحالية والتبعيات ./gradlew :module_name:testAllSuitesWithDependencies تُنشئ هذه السمة تقرير اختبار موحّدًا للوحدة الحالية واعتمادات المكتبة، وتدمج نتائج اختبارات الوحدات والاختبارات المبرمَجة. path_to_your_project/module_name/build/reports/tests/aggregated-test-report/