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

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

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

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

mkdir android11-tests-dev && cd android11-tests-dev && repo init -c -u https://android.googlesource.com/platform/manifest -b android11-tests-dev --use-superproject --partial-clone --partial-clone-exclude=platform/frameworks/base --clone-filter=blob:limit=10M && repo sync -c -j8

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

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

إنشاء CTS (الإصدار 14 من نظام التشغيل Android أو إصدار أقدم)

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:

Branch الإصدار المستهدف
android15-tests-dev ap3a

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

في وحدة تحكّم CTS، أدخِل:

tf> run cts --plan CTS

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

.

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

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

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

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

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

نوع واجهة برمجة التطبيقات تنسيق التعليق التوضيحي الملاحظات
الطريقة android.example.ClassA#methodA حالة الاستخدام الأكثر شيوعًا
طريقة تتضمّن قيم مفاتيح android.example.ClassB#methodB(KeyA) استخدِم هذا الخيار فقط عندما يستخدم الاختبار طريقة واجهة برمجة تطبيقات للتحقّق من صحة حقل، كما هو موضّح في هذا المثال.
الحقل android.example.ClassC#FieldA استخدِم هذا الخيار فقط عندما يتحقّق الاختبار من صحة حقل في واجهة برمجة التطبيقات مباشرةً، كما هو موضّح في هذا المثال.

إذا كان الاختبار يتحقّق من أحد متطلبات CDD، أضِف تعليقًا توضيحيًا إلى معرّف المتطلب (بما في ذلك معرّف قسم CDD ومعرّف المتطلب) باستخدام @CddTest في رمز اختبار CTS كما هو موضّح في المثال التالي. في رسالة عملية الإيداع، أشر إلى متطلبات 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 Verifier، ضع تعليقًا توضيحيًا على كل نشاط في AndroidManifest.xml باستخدام معرّف CDD ذي الصلة. تتشابه تنسيقات حقول القيم مع تنسيقات تعليقات Java التوضيحية في CTS. في رسالة الالتزام، أشر إلى متطلبات CDD التي يتم فرضها من خلال الإشارة إلى معرّف متطلبات CDD. 


  <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>

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

يُرجى ذكر سبب ضرورة إضافة الاختبار بوضوح، وإضافة روابط ذات صلة للحصول على الدعم. بالنسبة إلى اختبارات CTS-D، يجب تضمين رابط لاقتراح الاختبار الذي أنشأته في Google Issue Tracker كجزء من عملية إرسال CTS-D.

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

على سبيل المثال، يمكنك إضافة ملف 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" />

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

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

على سبيل المثال، اختبار CTS لحزمة Java android.widget.TextView هو android.widget.cts.TextViewTest واسم حزمة Java هو android.widget.cts واسم الفئة هو TextViewTest.

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

تعتمد بنية الدليل ونموذج الرمز البرمجي على ما إذا كنت تستخدم الإصدار 1 أو الإصدار 2 من CTS.

CTS الإصدار 1

بالنسبة إلى الإصدار 6.0 من نظام التشغيل Android أو الإصدارات الأقدم، استخدِم الإصدار 1 من مجموعة اختبار التوافق (CTS). بالنسبة إلى الإصدار 1 من مجموعة اختبار التوافق، يتوفّر الرمز النموذجي على cts/tests/tests/example.

تبدو بنية الدليل في اختبارات CTS الإصدار 1 على النحو التالي: 

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

CTS الإصدار 2

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

تبدو بنية دليل CTS الإصدار 2 على النحو التالي: 

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

حِزم العيّنات الجديدة

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

CTS الإصدار 1

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

CTS الإصدار 2

استخدِم الاختبار النموذجي /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 يحتوي على الرمز البرمجي الخاص بالنظام الأساسي وملف Android.mk makefile.

يحتوي ملف 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 إليها أو إزالتها.

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

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

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

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

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

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

الإصدار مستوى واجهة برمجة التطبيقات فرع التطوير معدّل الإصدار
+16 36+ Internal gerrit ربع سنوي
15 35 android15-tests-dev ربع سنوي
14 34 android14-tests-dev ربع سنوي
13 33 android13-tests-dev ربع سنوي

تواريخ مهمة خلال الإصدار

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

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

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

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

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

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

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

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