פיתוח CTS

איך מאתחלים את לקוח ה-Repo

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

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

יצירה והפעלה של CTS

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

cd /path/to/android/root
make cts -j32 TARGET_PRODUCT=aosp_arm64
cts-tradefed

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

tf> run cts --plan CTS

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

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

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

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

הוספת הערת Java

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

אם הבדיקה שלך מאמתת דרישת 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' תהליך הגשת 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 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 גרסה 2. אפשר לקרוא פרטים נוספים במאמר בנושא בדיקה לדוגמה בפרויקט קוד פתוח של 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. קובץ ה-Mac הזה משמש את build/core/tasks/cts.mk לשלב את כל הבדיקות וליצור את חבילת ה-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: יוצרים ספרייה ברמה הבסיסית (root) של הפרויקט ליד src, עם תיקיית ה-Native שמכיל את הקוד 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 ברמה הבסיסית (root) של כדי לבנות את קוד ה-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 או VTS ב-AOSP, צריך לבחור את הסתעפות הפיתוח. לפי רמות ה-API שעליהן חל התיקון.

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

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

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

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

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

• בסוף השבוע הראשון: הקפאת הקוד. השינויים מוזגו בהסתעפות עד שהקפאת הקוד תטופל לגרסה החדשה של 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 המנוגד.

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