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

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

الجدول 2: 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 (لا شيء) توقف القيود المفروضة على استخدام واجهات برمجة التطبيقات المخفية. لمزيد من المعلومات حول واجهات برمجة التطبيقات المخفية وتأثيرها على تطبيقك، يُرجى الاطّلاع على القيود المفروضة على الواجهات غير المضمّنة في حزمة تطوير البرامج (SDK).

خيارات وسائل الدفع في AM

تمرّر أداة 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 --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/