CTS 開發

初始化 Repo 用戶端

請按照「下載來源」一節的操作說明，取得及建構 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 控制台：

注意：您可以改用 aosp_x86_64，而非 aosp_arm64。

建構 CTS (Android 14 或更早版本)

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

建構 CTS (Android 開放原始碼計畫 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

在 CTS 控制台中，輸入：

tf> run cts --plan CTS

撰寫 CTS 測試

如要編寫開發人員驅動的 CTS (CTS-D) 測試，請先按照 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 驗證器，請在 AndroidManifest.xml 中為每個活動加上相關 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 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 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/CtsTestCaseList.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 目錄，例如 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 檔案，建構原生程式碼並依附於該程式碼，如下所示：

# 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 版本發布時間表如下。

注意：這個時間表僅供參考，我們會隨著特定 Android 版本的 CTS 趨於成熟而更新。

版本	API 級別	開發分支	發布頻率
16+	36+	內部 Gerrit	每季
15	35	android15-tests-dev	每季
14	34	android14-tests-dev	每季
13	33	android13-tests-dev	每季

注意：我們不會再發布 4.2 至 12.1 版的更新。

發布期間的重要日期

• 第一週結束：程式碼凍結。在程式碼凍結前合併到分支機構的變更，都會納入下一個 CTS 版本。如果是在程式碼凍結後或選定發布候選版本後提交至分支版本，系統會將這些提交內容納入後續版本。
• 第二或第三週：CTS 會發布在「Compatibility Test Suite 下載」頁面。

自動合併流程

我們已設定 CTS 開發分支，因此提交至各分支的變更會自動合併至較高的分支。

如要直接變更 AOSP 測試開發分支，自動合併路徑如下：
android13-tests-dev > android14-tests-dev > android15-tests-dev

• 如果是 CTS 16 以上版本，審查人員會將變更相應地選取到內部 Gerrit。

如果變更清單 (CL) 無法正確合併，系統會傳送電子郵件給修補程式作者，說明如何解決衝突。在大多數情況下，修補程式的作者可以使用這些指示，略過有衝突的 CL 自動合併作業。

如果舊版分支需要變更，則必須從新版分支挑選修補程式。

如果測試變更適用於下一個 Android 版本，上傳提議的變更後，Google 會審查該變更，如果接受，就會將其併入內部 Gerrit。