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

איך יוצרים 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, צריך לעיין בטבלה הבאה:

סניף גרסת יעד
android15-tests-dev ap3a

הרצת 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. צריך להשתמש בפורמט המתאים מבין הדוגמאות הבאות:

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

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

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

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

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

גרסה רמת ממשק API: ענף פיתוח תדירות הפרקים
16+ 36+ Gerrit פנימי רבעוני
15 35 android15-tests-dev רבעוני
14 34 android14-tests-dev רבעוני
13 33 android13-tests-dev רבעוני

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

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

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

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

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

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

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

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

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