اعتبارًا من 27 آذار (مارس) 2025، ننصحك باستخدام android-latest-release بدلاً من aosp-main لإنشاء AOSP والمساهمة فيه. لمزيد من المعلومات، يُرجى الاطّلاع على التغييرات في AOSP.

تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

مثال على الاختبارات التي تتضمّن أدوات قياس الأداء الذاتي
تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

عند بدء اختبار أداة قياس الأداء، تتم إعادة تشغيل الحزمة المستهدفة مع إدخال رمز أداة قياس الأداء وبدء تنفيذه. أحد الاستثناءات هو أنّ الحزمة المستهدَفة هنا لا يمكن أن تكون إطار عمل تطبيق Android نفسه، مثل الحزمة android، لأنّ ذلك يؤدي إلى موقف متناقض يتطلّب إعادة تشغيل إطار عمل Android، وهو الإطار الذي يدعم وظائف النظام، بما في ذلك أداة القياس نفسها.

وهذا يعني أنّه لا يمكن لاختبار أداة القياس إدخال نفسه في إطار عمل Android ، المعروف أيضًا باسم خادم النظام، لتنفيذه. لاختبار إطار عمل Android ، لا يمكن لرمز الاختبار استدعاء سوى مساحات عرض واجهات برمجة التطبيقات المتاحة للجميع، أو تلك التي تم الكشف عنها باستخدام لغة تعريف واجهة Android AIDL المتوفّرة في شجرة مصدر النظام الأساسي. بالنسبة إلى هذه الفئة من الاختبارات، ليس من المفيد استهداف أي حزمة معيّنة. لذلك، من المعتاد أن يتمّ تحديد هذه الأدوات لاستهداف حزمة تطبيق الاختبار الخاصة بها، كما هو محدّد في علامة <manifest> الخاصة بها من AndroidManifest.xml.

استنادًا إلى المتطلبات، قد تفي حزم تطبيقات الاختبار في هذه الفئة أيضًا بما يلي:

أنشطة الحِزم مطلوبة للاختبار.
شارِك رقم تعريف المستخدم مع النظام.
أن تكون موقَّعة باستخدام مفتاح المنصة
أن يتم تجميعها باستخدام مصدر إطار العمل بدلاً من حزمة SDK العامة

يُشار أحيانًا إلى فئة اختبارات الأدوات باسم الأدوات الذاتية. في ما يلي بعض الأمثلة على اختبارات الأدوات الذاتية في مصدر المنصة:

يتناول المثال الذي نتناوله هنا كتابة اختبار أداة قياس جديد مع ضبط الحزمة المستهدفة على حزمة تطبيق الاختبار الخاصة به. يستخدم هذا الدليل الاختبار التالي ليكون بمثابة مثال:

اختبار Hello World Instrumentation

ننصحك بالتصفّح في الرمز أولاً للحصول على فكرة تقريبية قبل المتابعة.

تحديد موقع مصدر

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

بافتراض أنّ الموقع الجذر لمصدر المكوّن هو <component source root>، تحتوي معظم المكوّنات على مجلّدي src وtests ضمنه، وبعض الملفات الإضافية مثل Android.mk (أو مجزّأة إلى ملفات .mk إضافية)، ملف البيان AndroidManifest.xml وملف إعدادات الاختبار ‎"AndroidTest.xml".

بما أنّك تضيف اختبارًا جديدًا تمامًا، قد تحتاج على الأرجح إلى إنشاء الدليل tests بجانب المكوّن src، وملؤه بالمحتوى.

في بعض الحالات، قد يكون لدى فريقك المزيد من هياكل الدلائل ضمن tests نظرًا للحاجة إلى تجميع مجموعات مختلفة من الاختبارات في حِزم apk فردية. وفي هذه الحالة، عليك إنشاء دليل فرعي جديد ضمن tests.

بغض النظر عن البنية، سينتهي بك الأمر بملء الدليل tests أو الدليل الفرعي الذي تم إنشاؤه حديثًا بملفات مشابهة لما هو متوفر في الدليل instrumentation في نموذج تغيير gerrit. يتم شرح تفاصيل كل ملف لاحقًا في هذا المستند.

ملف البيان

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

إذا لم تكن على دراية بملف AndroidManifest.xml، يمكنك الرجوع إلى نظرة عامة على ملف بيان التطبيق.

في ما يلي نموذج لملف AndroidManifest.xml:

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
  android:sharedUserId="android.uid.system"
  package="android.test.example.helloworld" >

    <application>
       <uses-library android:name="android.test.runner"/>
    </application>

    <instrumentation android:name="androidx.test.runner.AndroidJUnitRunner"
                     android:targetPackage="android.test.example.helloworld"
                     android:label="Hello World Test"/>

</manifest>

في ما يلي بعض الملاحظات حول ملف البيان:

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="android.test.example.helloworld" >

سمة package هي اسم حزمة التطبيق: وهو المعرّف الفريد الذي يستخدمه إطار عمل تطبيقات Android لتحديد التطبيق (أو في هذا السياق: تطبيق الاختبار). يمكن لكل مستخدم في النظام تثبيت تطبيق واحد فقط يحمل اسم الحزمة هذا.

بالإضافة إلى ذلك، تكون سمة package هذه هي نفسها القيمة التي تعرضها ComponentName#getPackageName() ، وهي أيضًا القيمة نفسها التي ستستخدمها للتفاعل مع مختلف pmسمات الفرعية التي تستخدم adb shell.

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

android:sharedUserId="android.uid.system"

يشير ذلك إلى أنّه في وقت التثبيت، يجب منح ملف APK هذا رقم تعريف المستخدم نفسه، أي هوية وقت التشغيل، مثل المنصة الأساسية. يُرجى العلم أنّ ذلك يعتمد على توقيع حزمة APK باستخدام الشهادة نفسها المستخدَمة في النظام الأساسي الأساسي (راجِع LOCAL_CERTIFICATE في قسم سابق)، إلا أنّهما مفهومان مختلفان:

بعض الأذونات أو واجهات برمجة التطبيقات محمية بالتوقيع، ما يتطلّب استخدام شهادة التوقيع نفسها.
تتطلّب بعض الأذونات أو واجهات برمجة التطبيقات هوية system للمتصل، ما يتطلّب من حزمة الاتصال مشاركة معرّف المستخدم مع system، إذا كانت حزمة منفصلة عن النظام الأساسي نفسه.

<uses-library android:name="android.test.runner" />

هذا مطلوب لجميع اختبارات أداة Instrumentation لأنّ الفئات ذات الصلة يتم تجميعها في ملف مكتبة JAR منفصل لإطار العمل، وبالتالي تتطلّب إدخالات إضافية لمسار البحث عن السلسلة البرمجية عند استدعاء حزمة الاختبار من خلال إطار عمل التطبيق.

android:targetPackage="android.test.example.helloworld"

ربما لاحظت أنّه تمّ تحديد سمة targetPackage هنا على أنّها سمة package نفسها المحدّدة في علامة manifest في هذا الملف. كما هو موضّح في أساسيات الاختبار، فإنّ فئة اختبارات الأدوات هذه مخصّصة عادةً لاختبار واجهات برمجة التطبيقات الخاصة بالإطارات، لذا ليس من المفيد كثيرًا أن تحتوي على حِزمة تطبيق مستهدفة محدّدة غير نفسها.

ملف إعدادات بسيط

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

ملف إعدادات معقّد

بالنسبة إلى هذه الحالات الأكثر تعقيدًا، عليك أيضًا كتابة ملف إعدادات اختبار لنظام اختبار Android، وهو Trade Federation.

يمكن أن تحدِّد إعدادات الاختبار خيارات إعداد الجهاز الخاصة وargv التلقائية لتوفير فئة الاختبار. يمكنك الاطّلاع على المثال على الرابط /platform_testing/tests/example/instrumentation/AndroidTest.xml.

تم تضمين لقطة شاشة هنا للتيسير:

<configuration description="Runs sample instrumentation test.">
  <target_preparer class="com.android.tradefed.targetprep.TestFilePushSetup"/>
  <target_preparer class="com.android.tradefed.targetprep.TestAppInstallSetup">
    <option name="test-file-name" value="HelloWorldTests.apk"/>
  </target_preparer>
  <target_preparer class="com.android.tradefed.targetprep.PushFilePreparer"/>
  <target_preparer class="com.android.tradefed.targetprep.RunCommandTargetPreparer"/>
  <option name="test-suite-tag" value="apct"/>
  <option name="test-tag" value="SampleInstrumentationTest"/>

  <test class="com.android.tradefed.testtype.AndroidJUnitTest">
    <option name="package" value="android.test.example.helloworld"/>
    <option name="runner" value="android.support.test.runner.AndroidJUnitRunner"/>
  </test>
</configuration>

في ما يلي بعض الملاحظات المحدّدة حول ملف إعداد الاختبار:

<target_preparer class="com.android.tradefed.targetprep.TestAppInstallSetup">
  <option name="test-file-name" value="HelloWorldTests.apk"/>
</target_preparer>

يطلب هذا من Trade Federation تثبيت HelloWorldTests.apk على الجهاز المستهدَف باستخدام target_preparer محدّد. هناك العديد من أدوات إعداد الأجهزة المستهدفة التي تتوفّر للمطوّرين في Trade Federation، ويمكن استخدامها لضمان إعداد الجهاز بشكل صحيح قبل تنفيذ الاختبار.

<test class="com.android.tradefed.testtype.AndroidJUnitTest">
  <option name="package" value="android.test.example.helloworld"/>
  <option name="runner" value="android.support.test.runner.AndroidJUnitRunner"/>
</test>

يحدِّد هذا العنصر فئة اختبار Trade Federation التي سيتم استخدامها لتنفيذ الاختبار و المرات التي يتم فيها تنفيذ الاختبار في الحزمة على الجهاز وإطار عمل أداة تنفيذ الاختبار ، وهو JUnit في هذه الحالة.

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

ميزات JUnit4

يتيح استخدام مكتبة android-support-test كمشغِّل اختبارات إمكانية استخدام فئات اختبارات جديدة بأسلوب JUnit4، ويحتوي نموذج تغيير gerrit على بعض الاستخدامات الأساسية جدًا لميزاتها. يمكنك الاطّلاع على المثال على الرابط ‎/platform_testing/tests/example/instrumentation/src/android/test/example/helloworld/HelloWorldTest.java.

على الرغم من أنّ أنماط الاختبار تكون عادةً خاصة بفِرق المكوّنات، إلا أنّ هناك بعض أنماط الاستخدام المفيدة بشكل عام.

@RunWith(JUnit4.class)
public class HelloWorldTest {

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

    @BeforeClass
    public static void beforeClass() {
    ...
    @AfterClass
    public static void afterClass() {
    ...
    @Before
    public void before() {
    ...
    @After
    public void after() {
    ...
    @Test
    @SmallTest
    public void testHelloWorld() {
    ...

يتم استخدام التعليقَين التوضيحيَين @Before و@After على الطرق من خلال JUnit4 لتنفيذ إعداد الاختبار المُسبَق وإلغاء الإعداد بعد الاختبار. وبالمثل، يتم استخدام التعليقَين التوضيحيَين @BeforeClass و @AfterClass على الطرق من خلال JUnit4 لإجراء عملية الإعداد قبل تنفيذ جميع الاختبارات في فئة اختبار، ثم عملية الإزالة بعد ذلك. يُرجى العلم أنّه يجب أن تكون مثيلَا أسلوبَي الإعداد والإزالة على مستوى الفئة ثابتَين. بالنسبة إلى طرق الاختبار، لم يعُد من الضروري بدء اسم الأسلوب باستخدام test، على عكس الإصدارات السابقة من JUnit، بل يجب وضع تعليق توضيحي على كل منها باستخدام @Test. كالعادة، يجب أن تكون طُرق الاختبار علنية، وألا تحدّد أي قيمة معروضة، وألا تأخذ أيّ معلَمات، وقد تُعرِض استثناءات.

الوصول إلى فئة الأدوات

على الرغم من أنّه لم يتم تناول هذا الموضوع في مثال "مرحبًا" الأساسي، من الشائع إلى حدٍ ما أن يتطلّب اختبار Android الوصول إلى مثيل Instrumentation: هذه هي واجهة برمجة التطبيقات الأساسية التي توفّر إمكانية الوصول إلى سياقات التطبيقات وواجهات برمجة التطبيقات ذات الصلة بدورة حياة النشاط وغير ذلك.

بما أنّ اختبارات JUnit4 لم تعُد تتطلّب فئة أساسية مشتركة، لم يعد ضروريًا الحصول على مثيل Instrumentation من خلال InstrumentationTestCase#getInstrumentation()، وبدلاً من ذلك، يدير أداة تنفيذ الاختبار الجديدة الإعداد السياقي والبيئي الذي أنشأه إطار عمل الأدوات .InstrumentationRegistry

للوصول إلى مثيل فئة Instrumentation، ما عليك سوى استدعاء الطريقة الثابتة getInstrumentation() في فئة InstrumentationRegistry:

Instrumentation instrumentation = InstrumentationRegistry.getInstrumentation()

الإنشاء والاختبار على الجهاز

بالنسبة إلى حالات الاستخدام الأكثر شيوعًا، استخدِم Atest.

بالنسبة إلى الحالات الأكثر تعقيدًا التي تتطلّب تخصيصًا أكبر، اتّبِع تعليمات إعداد الأدوات.

مثال على الاختبارات التي تتضمّن أدوات قياس الأداء الذاتي تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.