CTS 開發

初始化存放區用戶端

請按照「下載來源」中的操作說明,取得並建構 Android 原始碼。發出 repo init 指令時,請使用 -b 指定特定的 CTS 分支。這樣可確保您的 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

建構 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 值:

Branch 目標版本
android15-tests-dev ap3a

在 CTS 主控台中輸入:

tf> run cts --plan CTS

編寫 CTS 測試

中的指示提交測試提案。

CTS 測試會使用 JUnit 和 Android 測試 API。請參閱「測試應用程式」教學課程,以及 cts/tests 目錄下現有的測試。CTS 測試大多遵循其他 Android 測試所用的慣例。

CTS 會在許多實際生產裝置上執行,因此測試必須遵守下列規則:

  • 考量不同的螢幕大小、方向和鍵盤配置。
  • 請只使用公開 API 方法。換句話說,請避免使用 hide 註解的所有類別、方法和欄位。
  • 避免使用可能無法在部分裝置上顯示的檢視區塊版面配置或資產尺寸。
  • 請勿依賴 Root 權限。

新增 Java 註解

如果您的測試會驗證 API 行為,請使用 @ApiTest 標註測試程式碼,並在 apis 欄位中列出所有相關 API。請使用下列範例中的適當格式:

API 類型 註解格式 附註
方法 android.example.ClassA#methodA 最常見的用途。
含有鍵值的方法 android.example.ClassB#methodB(KeyA) 僅在測試使用 API 方法驗證欄位時使用,如這個範例所示。
欄位 android.example.ClassC#FieldA 請僅在測試直接驗證 API 欄位時使用,如此範例所示。

如果您的測試驗證 CDD 要求,請在 CTS 測試程式碼中使用 @CddTest 註解要求 ID (包括 CDD 區段 ID 和要求 ID),如以下範例所示。在提交訊息中,請提及測試時測試的是哪項 CDD 需求,並參照 CDD 需求 ID。CDD 需求 ID 是版次 ID 和需求 ID 的組合,以斜線 (/) 連接,例如 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 中為每個 Activity 加上相關 CDD ID 的註解。值欄位的格式類似於 CTS 中的 Java 註解格式。在提交訊息中,提及要套用的 CDD 需求,並參照 CDD 需求 ID。


  <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 提交程序的一部分。

建立子企劃書

舉例來說,您可以在 android-cts/subplans 中新增 SubPlan.xml 檔案,如下所示:

<?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 字尾。每個測試案例都包含多個測試,每個測試通常會執行所測試類別的特定方法。這些測試會以目錄結構排列,其中測試會分組為不同的類別,例如「小工具」或「檢視畫面」。

舉例來說,Java 套件 android.widget.TextView 的 CTS 測試為 android.widget.cts.TextViewTest,其 Java 套件名稱為 android.widget.cts,類別名稱為 TextViewTest

  • Java 套件名稱
    CTS 測試的 Java 套件名稱是測試所測試類別的套件名稱,後面接著 .cts。在本範例中,套件名稱會是 android.widget.cts
  • 類別名稱
    CTS 測試的類別名稱是指要測試的類別名稱,加上「Test」這個字串。舉例來說,如果測試指定 TextView,類別名稱應為 TextViewTest
  • 模組名稱 (僅限 CTS 第 2 版)
    CTS 第 2 版會依模組分類安排測試。模組名稱通常是 Java 套件名稱的第二個字串 (在本例中為 widget)。

目錄結構和範例程式碼取決於您使用的是 CTS 1.0 版還是 CTS 2.0 版。

CTS 第 1 版

如果是 Android 6.0 以下版本,請使用 CTS v1。如需 CTS 1.0 的範例程式碼,請前往 cts/tests/tests/example

CTS 1.0 版測試中的目錄結構如下所示:

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 2.0 目錄結構如下所示:

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

新的樣本套件

新增測試時,可能沒有現有目錄可用來放置測試。在這種情況下,您需要建立目錄並複製適當的範例檔案。

CTS 第 1 版

如果您使用的是 CTS 1.0,請參考 cts/tests/tests/example 下的範例,然後建立新目錄。此外,請務必從 cts/CtsTestCaseList.mkAndroid.mk 新增至 CTS_COVERAGE_TEST_CASE_LIST,以便新增套件的模組名稱。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 目錄,例如 assetsjnilibsres。如要新增 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))

修正或移除測試

除了新增測試,您也可以修正或移除標有 BrokenTestKnownFailure 的測試。

提交變更

在 AOSP 中提交 CTS 或 VTS 修補程式時,請根據修補程式適用的 API 級別選擇開發分支。

  • 針對適用於多個 API 級別的變更,首先aosp/main 中開發修補程式,然後挑選最上游的測試分支。允許自動合併功能合併 AOSP 測試分支中的下游變更。如需分支版本清單和自動合併路徑資訊,請參閱版本時程表和分支資訊
  • 如果變更僅適用於特定 API 級別,請在提交訊息中使用「DO NOT MERGE」或「RESTRICT AUTOMERGE」,為正確的測試分支開發或挑選變更。

請按照提交修補程作業流程提供 CTS 變更。系統會指派審查人員審查你的變更內容。

發布時程和分支資訊

CTS 版本會依照這個時間表發布。

版本 API 級別 Branch 頻率
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 相衝突的自動合併作業。

如果較舊的分支需要變更,則必須從較新的分支中挑選補丁。