פיתוח CTS

אתחול של לקוח Repo

פועלים לפי ההוראות שבקטע הורדת קוד המקור כדי להוריד ולבנות את קוד המקור של Android. כשמריצים את הפקודה repo init, צריך לציין ענף CTS ספציפי באמצעות -b. כך תוכלו לוודא שהשינויים ב-CTS ייכללו בגרסאות הבאות של CTS.

בדוגמת הקוד הבאה אפשר לראות איך משתמשים ב-repo init.

איך יוצרים ומריצים את CTS

מריצים את הפקודות הבאות כדי ליצור את CTS ולהפעיל את מסוף CTS האינטראקטיבי:

איך יוצרים CTS (AOSP 14 או גרסאות קודמות)

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

גרסת build של 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, צריך לעיין בטבלה הבאה:

הרצת CTS

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

tf> run cts --plan CTS

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

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

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

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

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

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

אם הבדיקה מאמתת דרישה של 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 גרסה 1 זמין בכתובת 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 עם הקוד המקורי וקובץ 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 ברמה הבסיסית של הפרויקט כדי ליצור את קוד Native ולהסתמך עליו, כמו שמוצג בהמשך:

# 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, פועלים לפי תהליך העבודה של שליחת שינויים בקוד.

• בוחרים את ענף הפיתוח בהתאם לרמות ה-API שאליהן מתייחס הטלאי.
• מפתחים או בוחרים את השינויים בענף הבדיקה הנכון עם DO NOT MERGE או RESTRICT AUTOMERGE בהודעת הקומיט.

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

לוח זמנים לפרסום ופרטי הסניף

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

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

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

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

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

אם השינויים מתבצעים ישירות בענף פיתוח של בדיקות ב-AOSP, נתיב המיזוג האוטומטי הוא:
android13-tests-dev > android14-tests-dev > android15-tests-dev

• בגרסאות CTS 16 ואילך, בודק יבחר את השינוי באופן סלקטיבי ל-Gerrit הפנימי בהתאם.

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

אם השינוי נדרש בענף ישן יותר, צריך לבצע cherry-pick של התיקון מהענף החדש יותר.

לגבי שינויים לבדיקה שרלוונטיים לגרסה הבאה של Android, אחרי שמעלים שינוי מוצע, Google בודקת אותו, ואם הוא מתקבל, היא בוחרת אותו ומעבירה אותו ל-Gerrit הפנימי.