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

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

لإجراء اختبار من خلال سطر الأوامر، شغِّل 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 أو مع InstrumentationTestRunner وفئاتها الفرعية. يُرجى العلم أنّ استخدامها مع أي فئة أخرى ليس له أي تأثير.
--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. - ضع علامة على أزواج المفتاح/القيمة لاستخدامها مع عدّاء الاختبار

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

ملاحظة: يتطلب هذا الخيار إصدارًا يستند إلى إدارة الخدمات الجوّالة للمؤسسات (EMM) لتطبيق الاختبار، ويمكنك إنشاؤه باستخدام هدف 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.