تطوير مجموعة أدوات اختبار التوافق (CTS)

إعداد برنامج Repo

اتّبِع التعليمات الواردة في مقالة تنزيل رمز المصدر للحصول على رمز المصدر لنظام Android وإنشائه. عند تنفيذ الأمر repo init، حدِّد فرعًا معيّنًا من مجموعة أدوات اختبار التوافق (CTS) باستخدام -b. يضمن ذلك تضمين تغييراتك في مجموعة أدوات اختبار التوافق في الإصدارات اللاحقة من هذه المجموعة.

يوضّح رمز المثال التالي كيفية استخدام repo init.

إنشاء مجموعة أدوات اختبار التوافق وتشغيلها

نفِّذ الأوامر التالية لإنشاء مجموعة أدوات اختبار التوافق وبدء وحدة تحكّم مجموعة أدوات اختبار التوافق التفاعلية:

إنشاء مجموعة أدوات اختبار التوافق (AOSP 14 أو الإصدارات الأقدم)

cd /path/to/android/root
source build/envsetup.sh
make cts -j32 TARGET_PRODUCT=aosp_arm64
cts-tradefed

إنشاء مجموعة أدوات اختبار التوافق (AOSP 15)

cd /path/to/android/root
source build/envsetup.sh
make cts -j32 TARGET_PRODUCT=aosp_arm64 TARGET_RELEASE=target-release
cts-tradefed

يُرجى الرجوع إلى الجدول التالي لاختيار قيمة target-release:

تشغيل مجموعة أدوات اختبار التوافق

في وحدة تحكّم مجموعة أدوات اختبار التوافق، أدخِل:

tf> run cts --plan CTS

كتابة اختبارات مجموعة أدوات اختبار التوافق

تستخدم اختبارات مجموعة أدوات اختبار التوافق JUnit وواجهات برمجة التطبيقات لاختبار Android. راجِع البرنامج التعليمي اختبار تطبيقك والاختبارات الحالية ضِمن الدليل cts/tests. تتّبع اختبارات مجموعة أدوات اختبار التوافق في الغالب الاصطلاحات نفسها المستخدَمة في اختبارات Android الأخرى.

يتم تشغيل مجموعة أدوات اختبار التوافق على العديد من الأجهزة المتاحة للبيع، لذا يجب أن تتّبع الاختبارات القواعد التالية:

• مراعاة أحجام الشاشات المختلفة واتجاهاتها وتخطيطات لوحة المفاتيح
• استخدام طرق واجهة برمجة التطبيقات العامة فقط بعبارة أخرى، تجنَّب جميع الفئات والطرق والحقول التي تحمل التعليق التوضيحي hide.
• تجنُّب استخدام تخطيطات العرض أو الاعتماد على أبعاد مواد العرض التي قد لا تكون متوفّرة على بعض الأجهزة
• عدم الاعتماد على امتيازات المستخدم الجذر

إضافة تعليق توضيحي بلغة Java

إذا كان اختبارك يتحقّق من سلوك واجهة برمجة تطبيقات، أضِف التعليق التوضيحي @ApiTest إلى رمز الاختبار وأدرِج جميع واجهات برمجة التطبيقات المعنيّة في الحقل apis. استخدِم التنسيق المناسب من بين الـ أمثلة التالية:

إذا كان اختبارك يتحقّق من أحد متطلبات مستند تعريف التوافق (CDD)، أضِف التعليق التوضيحي @CddTest إلى رقم تعريف المتطلب (بما في ذلك رقم تعريف قسم مستند تعريف التوافق ورقم تعريف المتطلب) في رمز اختبار مجموعة أدوات اختبار التوافق كما هو موضّح في المثال التالي. في رسالة الإتمام، أشر إلى متطلبات مستند تعريف معايير التوافق (CDD) التي يختبرها اختبارك من خلال الإشارة إلى أرقام تعريف متطلبات مستند تعريف معايير التوافق (CDD). تتكوّن أرقام تعريف متطلبات مستند تعريف معايير التوافق (CDD) من مزيج من رقم تعريف القسم ورقم تعريف المتطلب، ويفصل بينهما شرطة مائلة (/) كما في 7.3.1/C-1-1.

/**
* Verify Passpoint configuration management APIs for a Passpoint
* @throws Exception
*/
    @CddTest(requirement="7.4.2.3/C-1-1,C-2-1")
    public void testAddPasspointConfigWithUserCredential() throws Exception {
        if (!WifiFeature.isWifiSupported(getContext())) {
            // skip the test if WiFi is not supported
            return;
        }      testAddPasspointConfig(generatePasspointConfig(generateUserCredential()));
    }

بالنسبة إلى أداة التحقّق من مجموعة أدوات اختبار التوافق (CTS)، أضِف التعليق التوضيحي إلى كل نشاط في AndroidManifest.xml باستخدام رقم تعريف مستند تعريف معايير التوافق (CDD) ذي الصلة. تشبه تنسيقات حقول القيم تنسيقات التعليقات التوضيحية بلغة Java في مجموعة أدوات اختبار التوافق. في رسالة الإتمام، أشر إلى متطلبات مستند تعريف معايير التوافق التي يتم فرضها من خلال الإشارة إلى رقم تعريف متطلبات مستند تعريف معايير التوافق.

  <activity>
    ......
    <!-- OPTIONAL: Add a meta data attribute to indicate CDD requirements. -->
    <meta-data android:name="cdd_test" android:value="7.4.1/C-4-1" />

    <!-- OPTIONAL: Add a meta data attribute to indicate APIs being tested. -->
    <meta-data android:name="api_test"
               android:value="com.example.MyClass#myMethod" />

    <!-- OPTIONAL: Add a metadata attribute to indicate the reason why the test doesn't enforce any CDD requirement but still useful in CTS-V. -->
    <meta-data android:name="non_compliance_test"
               android:value="detailed reasons" />
  </activity>

في رسالة الإتمام

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

إنشاء خطة فرعية

على سبيل المثال، يمكنك إضافة ملف SubPlan.xml في android-cts/subplans على النحو التالي:

<?xml version="1.0" encoding="utf-8" standalone="no"?>
<SubPlan version="2.0">
<Entry include="CtsSystemIntentTestCases" />
<Entry include="CtsSystemUiHostTestCases" />
<Entry include="CtsSecurityHostTestCases android.security.cts.SELinuxHostTest#testAospFileContexts" />
<Entry include="CtsSecurityHostTestCases android.security.cts.SELinuxHostTest#testAospServiceContexts" />
</SubPlan>

لتشغيل الخطة الفرعية:

run cts --subplan aSubPlan

تنسيق إدخال الخطة الفرعية هو:

Include a module name as follows:
<Entry include="MODULE_NAME" />

Include a package:
<Entry include="MODULE_NAME PACKAGE_NAME" />

Include a class:
<Entry include="MODULE_NAME PACKAGE_NAME.CLASS_NAME" />

Include an individual test:
<Entry include="MODULE_NAME PACKAGE_NAME.CLASS_NAME#TEST_NAME" />

تسمية الاختبار وموقعه

تستهدف معظم حالات اختبار مجموعة أدوات اختبار التوافق فئة معيّنة في واجهة برمجة تطبيقات Android. تحمل هذه الاختبارات أسماء حزم Java تنتهي باللاحقة cts وأسماء فئات تنتهي باللاحقة Test. تتكوّن كل حالة اختبار من اختبارات متعددة، ويُجري كل اختبار عادةً طريقة معيّنة للفئة التي يتم اختبارها. يتم ترتيب هذه الاختبارات في بنية دليل يتم فيها تجميع الاختبارات في فئات مختلفة، مثل "الأدوات" أو "طرق العرض".

على سبيل المثال، اختبار مجموعة أدوات اختبار التوافق لحزمة Java‏ android.widget.TextView هو android.widget.cts.TextViewTest، ويكون اسم حزمة Java هو android.widget.cts واسم الفئة هو TextViewTest.

• اسم حزمة Java
  اسم حزمة Java لاختبارات مجموعة أدوات اختبار التوافق هو اسم حزمة الفئة التي يختبرها الاختبار، متبوعًا بـ .cts. في مثالنا، سيكون اسم الحزمة android.widget.cts.
• اسم الفئة
  اسم الفئة لاختبارات مجموعة أدوات اختبار التوافق هو اسم الفئة التي يتم اختبارها مع إضافة "Test" في نهايتها. على سبيل المثال، إذا كان الاختبار يستهدف TextView، يجب أن يكون اسم الفئة TextViewTest.
• اسم الوحدة (مجموعة أدوات اختبار التوافق v2 فقط)
  تنظّم مجموعة أدوات اختبار التوافق v2 الاختبارات حسب الوحدة. عادةً ما يكون اسم الوحدة هو السلسلة الثانية من اسم حزمة Java (في مثالنا، widget).

تعتمد بنية الدليل ورمز نموذجي على ما إذا كنت تستخدم مجموعة أدوات اختبار التوافق v1 أو مجموعة أدوات اختبار التوافق v2.

مجموعة أدوات اختبار التوافق v1

بالنسبة إلى Android 6.0 أو الإصدارات الأقدم، استخدِم مجموعة أدوات اختبار التوافق v1. بالنسبة إلى مجموعة أدوات اختبار التوافق v1، يكون الرمز النموذجي في cts/tests/tests/example.

تبدو بنية الدليل في اختبارات مجموعة أدوات اختبار التوافق v1 على النحو التالي:

cts/
  tests/
    tests/
      package-name/
        Android.mk
        AndroidManifest.xml
        src/
          android/
            package-name/
              SampleDeviceActivity.java
              cts/
                SampleDeviceTest.java

مجموعة أدوات اختبار التوافق v2

بالنسبة إلى Android 7.0 أو الإصدارات الأحدث، استخدِم مجموعة أدوات اختبار التوافق v2. لمعرفة التفاصيل، اطّلِع على نموذج الاختبار في مشروع مفتوح المصدر لنظام Android (AOSP).

تبدو بنية دليل مجموعة أدوات اختبار التوافق v2 على النحو التالي:

cts/
  tests/
    module-name/
      Android.mk
      AndroidManifest.xml
      src/
        android/
          package-name/
            SampleDeviceActivity.java
            cts/
              SampleDeviceTest.java

حِزم نماذج جديدة

عند إضافة اختبارات جديدة، قد لا يكون هناك دليل حالي لوضع اختبارك فيه. في هذه الحالات، عليك إنشاء الدليل ونسخ ملفات النماذج المناسبة.

مجموعة أدوات اختبار التوافق v1

إذا كنت تستخدم مجموعة أدوات اختبار التوافق v1، يُرجى الرجوع إلى المثال ضِمن cts/tests/tests/example وإنشاء دليل جديد. احرِص أيضًا على إضافة اسم وحدة الحزمة الجديدة من Android.mk إلى CTS_COVERAGE_TEST_CASE_LIST في cts/CtsTestCaseList.mk. build/core/tasks/cts.mk يستخدم ملف makefile هذا لدمج جميع الاختبارات وإنشاء حزمة مجموعة أدوات اختبار التوافق النهائية.

مجموعة أدوات اختبار التوافق v2

استخدِم نموذج الاختبار /cts/tests/sample/ للبدء السريع في وحدة الاختبار الجديدة باتّباع الخطوات التالية:

1. لإنشاء دليل الاختبار ونسخ ملفات النماذج، نفِّذ ما يلي:

   mkdir cts/tests/module-name && cp -r cts/tests/sample/* cts/tests/module-name

2. انتقِل إلى cts/tests/module-name واستبدِل كل مثيلات "[Ss]ample" باصطلاح التسمية المقترَح من أعلاه.
3. عدِّل SampleDeviceActivity لتنفيذ الميزة التي تختبرها.
4. عدِّل SampleDeviceTest للتأكّد من نجاح النشاط أو تسجيل أخطائه.

أدلة إضافية

يمكنك أيضًا إضافة أدلة Android أخرى، مثل assets وjni وlibs وres. لإضافة رمز JNI، أنشِئ دليلاً في جذر المشروع بجانب src يتضمّن الرمز الأصلي وملف makefile‏ Android.mk.

يحتوي ملف makefile عادةً على الإعدادات التالية:

LOCAL_PATH := $(call my-dir)
include $(CLEAR_VARS)
LOCAL_MODULE := libCtsSample_jni

# don't include this package in any target
LOCAL_MODULE_TAGS := optional
LOCAL_SRC_FILES := list of source code files
LOCAL_C_INCLUDES := $(JNI_H_INCLUDE)

# Tag this module as a cts test artifact
LOCAL_COMPATIBILITY_SUITE := cts
LOCAL_SHARED_LIBRARIES := libnativehelper
LOCAL_SDK_VERSION := current
include $(BUILD_SHARED_LIBRARY)

ملف Android.mk

أخيرًا، عدِّل ملف Android.mk في جذر الـ مشروع لإنشاء الرموز البرمجية الأصلية والاعتماد عليها، كما هو موضّح أدناه:

# All tests should include android.test.runner.
LOCAL_JAVA_LIBRARIES := android.test.runner

# Includes the jni code as a shared library
LOCAL_JNI_SHARED_LIBRARIES := libCtsSample_jni

# Include for InstrumentationCtsTestRunner
LOCAL_STATIC_JAVA_LIBRARIES := ctstestrunner...
LOCAL_SDK_VERSION := currentinclude $(BUILD_CTS_PACKAGE)

#Tells make to look in subdirectories for more make files to include
include $(call all-makefiles-under,$(LOCAL_PATH))

إصلاح الاختبارات أو إزالتها

بالإضافة إلى إضافة اختبارات جديدة، يمكنك إصلاح الاختبارات التي تحمل التعليق التوضيحي BrokenTest أو KnownFailure أو إزالتها.

إرسال تغييراتك

اتّبِع سير عمل إرسال تغييرات الرمز البرمجي عند المساهمة بتغييرات في مجموعة أدوات اختبار التوافق.

• اختَر فرع التطوير استنادًا إلى مستويات واجهة برمجة التطبيقات التي ينطبق عليها التصحيح.
• طوِّر التغييرات أو اختَرها وادمجها في فرع الاختبار الصحيح مع إضافة DO NOT MERGE أو RESTRICT AUTOMERGE في رسالة الإتمام.

يتم تعيين مراجع لمراجعة التغيير واختياره ودمجه في Gerrit الداخلي وفقًا لذلك.

الجدول الزمني لإصدار الفيديوهات ومعلومات الفرع

تتّبع إصدارات مجموعة أدوات اختبار التوافق هذا الجدول الزمني.

تواريخ مهمة أثناء الإصدار

• نهاية الأسبوع الأول: تجميد الرمز البرمجي. يتم أخذ التغييرات التي تم دمجها في الفرع حتى تجميد الرمز البرمجي في الاعتبار للإصدار القادم من مجموعة أدوات اختبار التوافق. يتم أخذ عمليات الإرسال إلى الفرع بعد تجميد الرمز البرمجي أو بعد اختيار مرشّح للإصدار في الاعتبار للإصدار اللاحق.
• الأسبوع الثاني أو الثالث: يتم نشر مجموعة أدوات اختبار التوافق في صفحة تنزيلات مجموعة أدوات اختبار التوافق.

سير عمل الدمج التلقائي

تم إعداد فروع تطوير مجموعة أدوات اختبار التوافق بحيث يتم دمج التغييرات المُرسَلة إلى كل فرع تلقائيًا في الفروع الأعلى.

بالنسبة إلى التغييرات التي يتم إجراؤها مباشرةً على فرع تطوير اختبار AOSP، يكون مسار الدمج التلقائي:
android13-tests-dev > android14-tests-dev > android15-tests-dev

• بالنسبة إلى الإصدارات 16 والإصدارات الأحدث من مجموعة أدوات اختبار التوافق، سيختار المراجع التغيير ويدمجه في Gerrit الداخلي وفقًا لذلك.

إذا تعذّر دمج قائمة التغييرات بشكلٍ صحيح، يتم إرسال رسالة إلكترونية إلى مؤلّف التصحيح تتضمّن تعليمات حول كيفية حلّ التعارض. في معظم الحالات، يمكن لمؤلّف التصحيح استخدام التعليمات لتخطّي الدمج التلقائي لقائمة التغييرات المتعارضة.

إذا كان فرع أقدم يتطلّب التغيير، يجب اختيار التصحيح ودمجه من الفرع الأحدث.

بالنسبة إلى تغييرات الاختبارات التي تنطبق على إصدار Android التالي، بعد تحميل تغيير مقترَح، تراجعه Google، وإذا تم قبوله، ستختاره وتدمجه في Gerrit الداخلي.