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

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

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

كما هو موضح في الجدول 1، تحفظ Gradle نتائج الاختبارات الآلية في دليل build/ لكل وحدة تختبرها. ومع ذلك، عند إجراء الاختبارات على وحدات متعددة، قد يكون من المفيد دمج كل نتائج الاختبار في تقرير واحد. لإنشاء تقرير واحد عند إجراء الاختبارات على وحدات متعدّدة، اتّبِع الخطوات التالية:

  1. في ملف build.gradle على مستوى المشروع، أضِف ما يلي بعد حظر buildscript{}:

    رائع

    apply plugin: 'android-reporting'

    Kotlin

    apply(plugin = "android-reporting")

  2. استدعِ المهمة test أو connectedAndroidTest من خلال المهمة mergeAndroidReports. مثلاً:

    ./gradlew connectedAndroidTest mergeAndroidReports

    لتخطّي إخفاقات الاختبارات حتى ينتهي Gradle من إجراء جميع الاختبارات المتبقية، أضِف الخيار --continue:

    ./gradlew connectedAndroidTest mergeAndroidReports --continue

عند انتهاء Gradle من إجراء الاختبارات، يتم حفظ النتائج المجمّعة في دليل path_to_your_project/build/.

إجراء الاختبارات باستخدام 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 (الموثَّقة في القسم خيارات أداة صباحًا).
-e <test_options> توفر خيارات اختبار كأزواج المفتاح/القيمة. وتمرِّر أداة am instrument هذه الفئات إلى فئة الأدوات المحدّدة باستخدام طريقة onCreate() الخاصة بها. ويمكنك تحديد مواضع ورود متعددة لـ -e <test_options>. يتم توضيح المفاتيح والقيم في قسم خيارات أداة AM. لا يمكنك استخدام أزواج المفتاح/القيمة هذه إلا مع AndroidJUnitRunner أو مع InstrumentationTestRunner وفئاتها الفرعية. وعند استخدامها مع أي فئة أخرى، ليس هناك أي تأثير.
--no-hidden-api-checks (بدون) لإيقاف القيود المفروضة على استخدام واجهات برمجة التطبيقات المخفية. لمزيد من المعلومات حول واجهات برمجة التطبيقات المخفية وكيفية تأثيرها في تطبيقك، يُرجى الاطّلاع على القيود المفروضة على الواجهات غير المتوفرة في حزمة تطوير البرامج (SDK).

خيارات أداة صباحًا

تمرِّر أداة 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 الموضّح في الإدخال التالي.

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