פיתוח 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 האינטראקטיבי, מריצים את הפקודות הבאות:

build של CTS‏ (AOSP 14 ואילך)

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

פיתוח CTS (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, אפשר לעיין בטבלה הבאה:

סניף Target Release
android15-tests-dev ap3a

במסוף CTS, מזינים:

tf> run cts --plan CTS

כתיבת בדיקות CTS

.

בבדיקות CTS נעשה שימוש ב-JUnit ובממשקי ה-API לבדיקת Android. כדאי לעיין במדריך בדיקת האפליקציה ובבדיקות הקיימות בספרייה cts/tests. ברוב המקרים, בדיקות CTS פועלות לפי אותן מוסכמות שמוגדרות בבדיקות אחרות של Android.

בדיקת CTS פועלת במכשירי ייצור רבים, ולכן הבדיקות צריכות לפעול לפי הכללים הבאים:

  • חשוב להביא בחשבון את הבדלים בגדלים, בכיוונים ובפריסות של המקלדות של המסכים השונים.
  • להשתמש רק בשיטות API ציבוריות. במילים אחרות, צריך להימנע מכל הכיתות, השיטות והשדות עם ההערה hide.
  • כדאי להימנע משימוש בפריסות תצוגה או להסתמך על המימדים של נכסים שיכול להיות שלא יהיו במכשירים מסוימים.
  • לא מסתמכים על הרשאות root.

הוספת הערה ב-Java

אם הבדיקה מאמתת התנהגות של API, צריך להוסיף הערה לקוד הבדיקה באמצעות @ApiTest ולפרט את כל ממשקי ה-API המעורבים בשדה apis. צריך להשתמש בפורמט המתאים מבין הדוגמאות הבאות:

סוג ה-API פורמט ההערה הערות
שיטה android.example.ClassA#methodA התרחיש לדוגמה הנפוץ ביותר.
שיטה עם ערכי מפתח android.example.ClassB#methodB(KeyA) משתמשים באפשרות הזו רק כשבבדיקה נעשה שימוש בשיטת API כדי לאמת שדה, כמו בדוגמה הזו.
שדה android.example.ClassC#FieldA משתמשים באפשרות הזו רק כשהבדיקה מאמתת שדה API ישירות, כמו בדוגמה הזו.

אם הבדיקה מאמתת דרישה של CDD, צריך להוסיף הערה למזהה הדרישה (כולל מזהה הקטע של CDD ומזהה הדרישה) באמצעות @CddTest בקוד הבדיקה של CTS, כפי שמתואר בדוגמה הבאה. בהודעת ה-commit, ציינו את דרישת ה-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 הוא השם של הכיתה שנבדקת, עם הסיומת 'Test'. לדוגמה, אם ניסוי מטרגט את TextView, שם המחלקה צריך להיות TextViewTest.
  • שם המודול (CTS v2 בלבד)
    ב-CTS v2, הבדיקות מאורגנות לפי מודול. שם המודול הוא בדרך כלל המחרוזת השנייה של שם החבילה ב-Java (בדוגמאות שלנו, widget).

מבנה הספרייה והקוד לדוגמה משתנים בהתאם לגרסת CTS שבה אתם משתמשים – CTS v1 או CTS v2.

CTS v1

ב-Android מגרסה 6.0 ומטה, משתמשים ב-CTS v1. ב-CTS v1, הקוד לדוגמה נמצא בכתובת cts/tests/tests/example.

מבנה הספריות בבדיקות של CTS v1 נראה כך: 

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

CTS v2

ב-Android 7.0 ואילך, משתמשים ב-CTS v2. פרטים נוספים זמינים בבדיקה לדוגמה בפרויקט הקוד הפתוח של Android‏ (AOSP).

מבנה הספריות של CTS v2 נראה כך: 

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

חבילות דוגמה חדשות

כשאתם מוסיפים בדיקות חדשות, יכול להיות שלא תהיה ספרייה קיימת שבה תוכלו להציב את הבדיקה. במקרים כאלה, צריך ליצור את הספרייה ולהעתיק את קובצי הדוגמה המתאימים.

CTS v1

אם אתם משתמשים ב-CTS v1, עיינו בדוגמה בקטע cts/tests/tests/example וליצור ספרייה חדשה. בנוסף, חשוב להוסיף את שם המודול של החבילה החדשה מ-Android.mk ל-CTS_COVERAGE_TEST_CASE_LIST בקובץ cts/CtsTestCaseList.mk. build/core/tasks/cts.mk משתמש בקובץ ה-makefile הזה כדי לשלב את כל הבדיקות וליצור את חבילת ה-CTS הסופית.

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

שליחת השינויים

כששולחים תיקוני CTS או VTS ב-AOSP, צריך לבחור את ההסתעפות לפיתוח בהתאם לרמות ה-API שאלהן התיקון רלוונטי.

  • לשינויים שחלים על כמה רמות API, קודם מפתחים תיקון ב-aosp/main ואז בוחרים את השינויים הרצויים ומעבירים אותם להענף העליון ביותר לבדיקה. מאפשרים למיזוג האוטומטי למזג את השינויים בענף הבדיקה של AOSP. בלוח הזמנים לפרסום גרסאות והמידע על ההסתעפויות מפורטות רשימת ההסתעפויות והמידע על נתיב המיזוג האוטומטי.
  • לשינויים שספציפיים לרמת API מסוימת, מפתחים או בוחרים את השינויים שרוצים להוסיף להסתעפות הנכונה לבדיקה, ומוסיפים את ההודעה DO NOT MERGE או RESTRICT AUTOMERGE להודעת השמירה.

כדי לשלוח שינויים ל-CTS, פועלים לפי תהליך העבודה לשליחת תיקונים. בודק יוקצה לבדיקה של השינוי בהתאם.

לוח הזמנים לפרסום ומידע על ההסתעפות

הגרסאות של CTS פורסמות לפי לוח הזמנים הזה.

גרסה רמת ממשק API: סניף תדירות
15 35 android15-tests-dev רבעוני
14 34 android14-tests-dev רבעוני
13 33 android13-tests-dev רבעוני
12L 32 android12L-tests-dev רבעוני
12 31 android12-tests-dev רבעוני

תאריכים חשובים במהלך ההשקה

  • סוף השבוע הראשון: הקפאת הקוד. שינויים שמוזגו בהסתעפות עד להקפאת הקוד נלקחים בחשבון לגרסה הבאה של CTS. בקשות להוספת קוד להסתעפות יתקבלו אחרי הקפאת הקוד או אחרי שבוחרים גרסה מועמדת להפצה.
  • השבוע השני או השלישי: CTS פורסם ב-AOSP.

תהליך המיזוג האוטומטי

ההסתעפויות של CTS לפיתוח הוגדרו כך ששינויים שנשלחים לכל ההסתעפויות ימוזגו באופן אוטומטי להסתעפויות ברמה גבוהה יותר.

לשינויים ישירות בהסתעפות של מפתחי בדיקות ב-AOSP, נתיב המיזוג האוטומטי הוא:
android11-tests-dev > android12-tests-dev > android12L-tests-dev > android13-tests-dev > android14-tests-dev > android15-tests-dev > aosp-main

לשינויים בגרסת Android הבאה בלבד, נתיב המיזוג האוטומטי הוא:
aosp-main > <Internal git_main>.

אם אי אפשר למזג רשימת שינויים (CL) בצורה תקינה, יישלח לאימייל של מחבר התיקון אימייל עם הוראות לפתרון הסכסוך. ברוב המקרים, מחבר התיקון יכול להשתמש בהוראות כדי לדלג על המיזוג האוטומטי של ה-CL המנוגד.

אם השינוי נדרש להסתעפות ישנה יותר, צריך לבחור את התיקון מההסתעפות החדשה יותר.