إجراء الاختبارات (Atest)

Atest هي أداة سطر أوامر تتيح للمستخدمين إنشاء اختبارات Android وتثبيتها وتشغيلها على الجهاز، ما يسرع بشكل كبير من إعادة تشغيل الاختبارات بدون الحاجة إلى معرفة خيارات سطر أوامر مجموعة أدوات اختبار Trade Federation. توضّح هذه الصفحة كيفية استخدام Atest لإجراء اختبارات Android.

للحصول على معلومات عامة عن كتابة اختبارات لنظام التشغيل Android، يُرجى الاطّلاع على مقالة اختبار نظام التشغيل Android.

للحصول على معلومات عن البنية العامة لخدمة Atest، يُرجى الرجوع إلى دليل مطوّري Atest.

للحصول على معلومات عن إجراء الاختبارات في ملفات TEST_MAPPING من خلال Atest، يُرجى الاطّلاع على مقالة إجراء الاختبارات في ملفات TEST_MAPPING.

لإضافة ميزة إلى Atest، اتّبِع خطوات عملية عمل مطوّري Atest.

إعداد البيئة

لإعداد بيئة Atest، اتّبِع التعليمات الواردة في إعداد البيئة واختيار هدف وإنشاء الرمز.

الاستخدام الأساسي

تأخذ أوامر Atest الشكل التالي:

atest test-to-run [optional-arguments]

الوسيطات الاختيارية

يسرد الجدول التالي الوسيطات الأكثر استخدامًا. يمكنك الاطّلاع على القائمة الكاملة من خلال atest --help.

Option خيار طويل الوصف
-b --build تُنشئ استهدافات اختبارية. (تلقائي)
-i --install تثبيت عناصر الاختبار (ملفات APK) على الجهاز (تلقائي)
-t --test يُجري الاختبارات. (تلقائي)
-s --serial يُجري الاختبارات على الجهاز المحدّد. يمكن اختبار جهاز واحد في كل مرة.
-d --disable-teardown إيقاف إزالة الاختبار وتنظيفه
--dry-run يمكنك إجراء عمليات تجريبيّة في Atest بدون إنشاء الاختبارات أو تثبيتها أو إجرائها.
-m --rebuild-module-info يفرض إعادة إنشاء ملف module-info.json.
-w --wait-for-debugger ينتظر انتهاء برنامج تصحيح الأخطاء قبل التنفيذ.
-v --verbose تعرِض هذه القيمة التسجيل على مستوى تصحيح الأخطاء.
--iterations تُجري حلقة الاختبار الاختبارات إلى أن يتم الوصول إلى الحد الأقصى من التكرار. (10 تلقائيًا)
--rerun-until-failure [COUNT=10] إعادة تشغيل جميع الاختبارات إلى أن يحدث تعذّر أو يتمّ الوصول إلى الحدّ الأقصى من التكرارات (10 تلقائيًا)
--retry-any-failure [COUNT=10] إعادة تشغيل الاختبارات غير الناجحة إلى أن يتم اجتيازها أو الوصول إلى الحد الأقصى من التكرار (10 تلقائيًا)
--start-avd يتم إنشاء جهاز افتراضي Android تلقائيًا وإجراء الاختبارات على الجهاز الافتراضي.
--acloud-create لإنشاء جهاز افتراضي Android باستخدام الأمر acloud.
--[CUSTOM_ARGS] تُحدِّد وسيطات مخصّصة لمشغّلي الاختبارات.
-a --all-abi يُجري الاختبارات لجميع تصاميم الأجهزة المتاحة.
--host يُجري الاختبار بالكامل على المضيف بدون جهاز.
ملاحظة: سيتعذّر إجراء اختبار مضيف يتطلّب جهازًا مزوّدًا بنظام التشغيل --host.
--history تعرِض نتائج الاختبار بترتيب زمني.
--latest-result لطباعة آخر نتيجة اختبار.

لمزيد من المعلومات عن -b و-i و-t، يُرجى الاطّلاع على القسم تحديد الخطوات: الإنشاء أو التثبيت أو التشغيل.

تحديد الاختبارات

لإجراء الاختبارات، حدِّد اختبارًا واحدًا أو أكثر باستخدام أحد العلامات التالية:

  • اسم الوحدة
  • الوحدة:الفئة
  • اسم الصف
  • اختبار دمج Tradefed
  • مسار الملف
  • اسم الحزمة

يجب الفصل بين الإشارات إلى اختبارات متعددة باستخدام مسافات، على النحو التالي:

atest test-identifier-1 test-identifier-2

اسم الوحدة

لتنفيذ وحدة اختبار كاملة، استخدِم اسم الوحدة. أدخِل الاسم كما يظهر في متغيّري LOCAL_MODULE أو LOCAL_PACKAGE_NAME في ملف Android.mk أو Android.bp الخاص بهذا الاختبار.

أمثلة:

atest FrameworksServicesTests
atest CtsVideoTestCases

الوحدة:الفئة

لتشغيل صف واحد ضمن وحدة، استخدِم الوحدة:الصف. الوحدة هي نفسها كما هو موضّح في اسم الوحدة. الفئة هي اسم فئة الاختبار في ملف .java، ويمكن أن يكون اسم الفئة المؤهَّلة بالكامل أو اسم الأساسي.

أمثلة:

atest CtsVideoTestCases:VideoEncoderDecoderTest
atest FrameworksServicesTests:ScreenDecorWindowTests
atest FrameworksServicesTests:com.android.server.wm.ScreenDecorWindowTests

اسم الصف

لتشغيل فئة واحدة بدون ذكر اسم وحدة بشكل صريح، استخدِم اسم الفئة.

أمثلة:

atest ScreenDecorWindowTests
atest VideoEncoderDecoderTest

اختبار دمج Tradefed

لإجراء الاختبارات المدمجة مباشرةً في TradeFed (غير الوحدات)، أدخِل الاسم كما يظهر في ناتج الأمر tradefed.sh list configs. على سبيل المثال:

لإجراء اختبار reboot.xml:

atest example/reboot

لإجراء اختبار native-benchmark.xml:

atest native-benchmark

مسار الملف

تتيح أداة Atest إجراء كلّ من الاختبارات المستندة إلى الوحدات والاختبارات المستندة إلى الدمج من خلال إدخال مسار ملف الاختبار أو الدليل الخاص بهما حسب الاقتضاء. ويتيح أيضًا تشغيل فئة واحدة من خلال تحديد مسار ملف Java الخاص بالفئة. يمكن استخدام المسارات النسبية والمطلقة.

تشغيل وحدة

توضِّح الأمثلة التالية طريقتَين لتشغيل وحدة CtsVideoTestCases باستخدام مسار ملف.

التشغيل من Android repo-root:

atest cts/tests/video

التشغيل من Android repo-root/cts/tests/video:

    atest .

تشغيل فئة اختبارية

يوضِّح المثال التالي كيفية تشغيل فئة معيّنة ضمن وحدة CtsVideoTestCases باستخدام مسار ملف.

من جهاز Android repo-root:

    atest cts/tests/video/src/android/video/cts/VideoEncoderDecoderTest.java

إجراء اختبار دمج

يوضّح المثال التالي كيفية إجراء اختبار دمج باستخدام مسار ملف من Android repo-root:

    atest tools/tradefederation/contrib/res/config/example/reboot.xml

اسم الحزمة

تتيح أداة Atest البحث عن الاختبارات حسب اسم الحزمة.

أمثلة:

    atest com.android.server.wm
    atest com.android.uibench.janktests

تحديد الخطوات: الإنشاء أو التثبيت أو التشغيل

استخدِم الخيارات -b و-i و-t لتحديد الخطوات التي تريد تنفيذها. إذا لم تحدّد خيارًا، سيتم تنفيذ جميع الخطوات.

  • أهداف الإنشاء فقط: atest -b test-to-run
  • إجراء الاختبارات فقط: atest -t test-to-run
  • تثبيت حزمة APK وإجراء الاختبارات: atest -it test-to-run
  • إنشاء التطبيق وتشغيله بدون تثبيته: atest -bt test-to-run

يمكن أن يفرض Atest على الاختبار تخطّي خطوة التنظيف أو الإزالة. تُجري العديد من الاختبارات، مثل CTS، عملية تنظيف للجهاز بعد إجراء الاختبار، لذا ستتعذّر محاولة إعادة إجراء الاختبار باستخدام -t بدون المَعلمة --disable-teardown. استخدِم -d قبل -t لتخطّي خطوة تنظيف الاختبار وإجراء الاختبار بشكلٍ متكرّر.

atest -d test-to-run
atest -t test-to-run

تنفيذ طُرق معيّنة

يتيح Atest تنفيذ طرق معيّنة ضمن فئة اختبار. على الرغم من أنّه يجب إنشاء الوحدت الكاملة، إلا أنّ ذلك يقلل من الوقت اللازم لإجراء الاختبارات. لتنفيذ methods معيّنة، حدِّد الصف باستخدام أيّ من الطرق المتوافقة لتحديد الصف (Module:Class، ومسار الملف، وما إلى ذلك) وأضِف اسم method:

atest reference-to-class#method1

عند تحديد طُرق متعدّدة، افصل بينها باستخدام فواصل:

atest reference-to-class#method1,method2,method3

أمثلة:

atest com.android.server.wm.ScreenDecorWindowTests#testMultipleDecors
atest FrameworksServicesTests:ScreenDecorWindowTests#testFlagChange,testRemoval

يوضّح المثالان التاليان الطرق المفضّلة لتشغيل طريقة واحدة، testFlagChange. يُفضَّل استخدام هذه الأمثلة بدلاً من استخدام اسم الفئة فقط، لأنّ تحديد الوحدة أو موقع ملف Java يسمح لأداة Atest بالعثور على الاختبار بسرعة أكبر بكثير.

باستخدام Module:Class:

atest FrameworksServicesTests:ScreenDecorWindowTests#testFlagChange

من جهاز Android repo-root:

atest frameworks/base/services/tests/wmtests/src/com/android/server/wm/ScreenDecorWindowTests.java#testFlagChange

يمكن تنفيذ طرق متعدّدة من فئات ووحدات مختلفة:

atest FrameworksServicesTests:ScreenDecorWindowTests#testFlagChange,testRemoval ScreenDecorWindowTests#testMultipleDecors

تنفيذ فئات متعددة

لتنفيذ فئات متعددة، افصل بينها بمسافات بالطريقة نفسها التي تُستخدَم لتنفيذ اختبارات متعددة. ينشئ Atest الفصول الدراسية ويشغّلها بكفاءة، لذا فإنّ تحديد مجموعة فرعية من الفصول الدراسية في وحدة معيّنة يُحسِّن الأداء مقارنةً بتشغيل الوحدة بأكملها.

لتشغيل صفَّين في الوحدة نفسها:

atest FrameworksServicesTests:ScreenDecorWindowTests FrameworksServicesTests:DimmerTests

لتنفيذ صفَّين دراسيَّين في وحدات مختلفة:

atest FrameworksServicesTests:ScreenDecorWindowTests CtsVideoTestCases:VideoEncoderDecoderTest

تشغيل ملفات GTest الثنائية

يمكن لأداة Atest تشغيل ملفات GTest الثنائية. استخدِم -a لإجراء هذه الاختبارات لجميع تصاميم الأجهزة المتاحة، والتي هي في هذا المثال armeabi-v7a (ARM‏ 32 بت) وarm64-v8a (ARM‏ 64 بت).

مثال على اختبار الإدخال:

atest -a libinput_tests inputflinger_tests

لاختيار ملف GTest ثنائي معيّن لتشغيله، استخدِم فاصلة منقوطة (:) لتحديد اسم الاختبار وعلامة الهاشتاغ (#) لتحديد طريقة فردية بشكل أكبر.

على سبيل المثال، بالنسبة إلى تعريف الاختبار التالي: 

TEST_F(InputDispatcherTest, InjectInputEvent_ValidatesKeyEvents)

لتنفيذ ما يلي لتحديد الاختبار بالكامل: 

atest inputflinger_tests:InputDispatcherTest

أو يمكنك إجراء اختبار فردي باستخدام ما يلي: 

atest inputflinger_tests:InputDispatcherTest#InjectInputEvent_ValidatesKeyEvents

إجراء الاختبارات في TEST_MAPPING

يمكن أن يُجري Atest اختبارات في ملفات TEST_MAPPING.

تشغيل اختبارات الفحص المُسبَق بشكل ضمني

يمكنك إجراء اختبارات ما قبل الإرسال في ملفات TEST_MAPPING في الدليل الحالي والدليل الرئيسي:

atest

يمكنك إجراء اختبارات الفحص قبل الإرسال في ملفات TEST_MAPPING في /path/to/project و أدلّتها الرئيسية:

atest --test-mapping /path/to/project

تنفيذ مجموعة اختبار محدّدة

مجموعات الاختبار المتاحة هي: presubmit(التلقائية) وpostsubmit mainline-presubmit وall.

يمكنك إجراء اختبارات ما بعد الإرسال في ملفات TEST_MAPPING في الدليلَين الحالي والرئيسي:

atest :postsubmit

يمكنك إجراء اختبارات من جميع المجموعات في ملفات TEST_MAPPING:

atest :all

يمكنك إجراء اختبارات ما بعد الإرسال في ملفات TEST_MAPPING في /path/to/project و المجلدات الرئيسية:

atest --test-mapping /path/to/project:postsubmit

يمكنك إجراء اختبارات الخطوط الرئيسية في ملفات TEST_MAPPING في /path/to/project والمجلدات الرئيسية:

atest --test-mapping /path/to/project:mainline-presubmit

إجراء الاختبارات في الأدلة الفرعية

بشكلٍ تلقائي، لا يبحث Atest عن الاختبارات إلا في ملفات TEST_MAPPING وما فوق (من الدليل الحالي أو الدليل المحدّد إلى الأدلة الرئيسية). إذا أردت أيضًا إجراء اختبارات في ملفات TEST_MAPPING في الأدلة الفرعية، استخدِم --include-subdirs لفرض أن تتضمّن أداة Atest هذه الاختبارات أيضًا:

atest --include-subdirs /path/to/project

إجراء الاختبارات في كلّ تكرار

يمكنك إجراء الاختبارات في التكرار من خلال تمرير الوسيطة --iterations. سواء اجتاز الاختبار أو تعذّر إجراؤه، سيكرّر Atest الاختبار إلى أن يتمّ الوصول إلى الحدّ الأقصى من التكرارات.

أمثلة:

بشكلٍ تلقائي، يتم تكرار Atest 10 مرات. يجب أن يكون عدد التكرارات عددًا صحيحًا موجبًا.

atest test-to-run --iterations
atest test-to-run --iterations 5

تسهِّل الأساليب التالية رصد الاختبارات غير الموثوق بها:

الطريقة 1: تنفيذ جميع الاختبارات إلى أن يحدث تعذّر أو يتمّ الوصول إلى الحدّ الأقصى من التكرارات

  • يمكنك إيقاف العملية عند حدوث خطأ أو عند بلوغ الجولة العاشرة (تلقائيًا). 
    atest test-to-run --rerun-until-failure
  • توقّف عند حدوث خطأ أو وصول التكرار إلى الجولة المائة. 
    atest test-to-run --rerun-until-failure 100

الطريقة 2: تنفيذ الاختبارات غير الناجحة فقط إلى أن يتم اجتيازها أو الوصول إلى الحد الأقصى من التكرار

  • لنفترض أنّ test-to-run يتضمّن حالات اختبار متعددة ويتعذّر إكمال أحد الاختبارات. يمكنك تنفيذ الاختبار الذي تعذّر إكماله 10 مرات فقط (تلقائيًا) أو إلى أن يتم اجتياز الاختبار. 
    atest test-to-run --retry-any-failure
  • أوقِف تشغيل الاختبار غير الناجح عند اجتيازه الجولة المائة أو بلوغها. 
    atest test-to-run --retry-any-failure 100

إجراء اختبارات على أجهزة افتراضية Android

يمكن لأداة Atest إجراء اختبارات على جهاز افتراضي Android تم إنشاؤه حديثًا. شغِّل acloud create لإنشاء جهاز افتراضي Android وإنشاء عناصر، ثم استخدِم الأمثلة التالية لإجراء اختباراتك.

ابدأ جهاز Android الظاهري ونفِّذ الاختبارات عليه:

acloud create --local-instance --local-image && atest test-to-run

بدء جهاز افتراضي Android كجزء من عملية تشغيل اختبارية:

atest test-to-run --acloud-create "--local-instance --local-image"

لمزيد من المعلومات، يمكنك تنفيذ acloud create --help.

تمرير الخيارات إلى الوحدة

يمكن لـ Atest تمرير الخيارات إلى وحدات الاختبار. لإضافة خيارات سطر أوامر TradeFed إلى عملية الاختبار، استخدِم البنية التالية وتأكَّد من أنّ المَعلمات المخصّصة تتّبع تنسيق خيارات سطر أوامر TradeFed.

atest test-to-run -- [CUSTOM_ARGS]

نقْل خيارات وحدة الاختبار إلى الجهات المعنيّة بإعداد الاختبار أو تشغيله والمُحدَّدة فيملف إعدادات الاختبار:

atest test-to-run -- --module-arg module-name:option-name:option-value
atest GtsPermissionTestCases -- --module-arg GtsPermissionTestCases:ignore-business-logic-failure:true

نقْل الخيارات إلى نوع أو فئة عداء:

atest test-to-run -- --test-arg test-class:option-name:option-value
atest CtsVideoTestCases -- --test-arg com.android.tradefed.testtype.JarHosttest:collect-tests-only:true

لمزيد من المعلومات عن خيارات الاختبار فقط، يُرجى الاطّلاع على مقالة تمرير الخيارات إلى الوحدات.