Phát triển Bộ thử nghiệm lượt chuyển đổi (CTS)

Khởi chạy ứng dụng khách Repo

Làm theo hướng dẫn trong phần Tải nguồn xuống để tải và tạo mã nguồn Android. Khi đưa ra lệnh repo init, hãy chỉ định một nhánh CTS cụ thể bằng -b. Điều này đảm bảo rằng các thay đổi của bạn đối với CTS sẽ được đưa vào các bản phát hành CTS tiếp theo.

Mã ví dụ sau đây cho thấy cách sử dụng 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

Tạo và chạy CTS

Thực thi các lệnh sau để tạo CTS và khởi động bảng điều khiển CTS tương tác:

Xây dựng CTS (AOSP 14 trở về trước)

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

Xây dựng CTS (AOSP 15 trở lên)

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

Vui lòng tham khảo bảng sau để chọn giá trị target-release:

Chi nhánh Bản phát hành mục tiêu
android15-tests-dev ap3a

Trong bảng điều khiển CTS, hãy nhập:

tf> run cts --plan CTS

Viết mã kiểm thử CTS

Các bài kiểm thử CTS sử dụng JUnit và API kiểm thử Android. Xem lại hướng dẫn Kiểm thử ứng dụng và các bài kiểm thử hiện có trong thư mục cts/tests. Các kiểm thử CTS chủ yếu tuân theo các quy ước tương tự được dùng trong các kiểm thử Android khác.

CTS chạy trên nhiều thiết bị sản xuất, vì vậy, các chương trình kiểm thử phải tuân theo các quy tắc sau:

  • Hãy tính đến nhiều kích thước màn hình, hướng và bố cục bàn phím.
  • Chỉ sử dụng các phương thức API công khai. Nói cách khác, hãy tránh tất cả các lớp, phương thức và trường có chú thích hide.
  • Tránh sử dụng bố cục thành phần hiển thị hoặc dựa vào kích thước của các thành phần có thể không có trên một số thiết bị.
  • Không dựa vào đặc quyền gốc.

Thêm chú thích Java

Nếu kiểm thử xác minh hành vi của API, hãy chú thích mã kiểm thử bằng @ApiTest và liệt kê tất cả API có liên quan trong trường apis. Sử dụng định dạng thích hợp trong số các ví dụ sau:

Loại API Định dạng chú thích Ghi chú
Phương thức android.example.ClassA#methodA Trường hợp sử dụng phổ biến nhất.
Phương thức có giá trị khoá android.example.ClassB#methodB(KeyA) Chỉ sử dụng khi kiểm thử của bạn sử dụng phương thức API để xác thực một trường, như trong ví dụ này.
Trường android.example.ClassC#FieldA Chỉ sử dụng khi kiểm thử của bạn xác thực trực tiếp một trường API, như trong ví dụ này.

Nếu kiểm thử của bạn xác minh một yêu cầu của CDD, hãy chú thích mã yêu cầu (bao gồm cả mã mục CDD và mã yêu cầu) bằng @CddTest trong mã kiểm thử CTS như trong ví dụ sau. Trong thông báo cam kết, hãy đề cập đến yêu cầu CDD nào được kiểm thử bằng cách tham chiếu đến mã yêu cầu CDD. Mã yêu cầu CDD là sự kết hợp giữa mã mục và mã yêu cầu, được kết nối bằng dấu gạch chéo (/) như trong 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()));
    }

Đối với Trình xác minh CTS, hãy chú thích từng Hoạt động trong AndroidManifest.xml bằng mã CDD có liên quan. Định dạng cho các trường giá trị tương tự như định dạng của chú thích Java trong CTS. Trong thông báo thay đổi, hãy đề cập đến yêu cầu CDD nào được thực thi bằng cách tham chiếu đến mã yêu cầu 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>

Trong thông báo xác nhận

Hãy nêu rõ lý do bạn cần thêm thử nghiệm và thêm các đường liên kết có liên quan để được hỗ trợ. Đối với các bài kiểm thử CTS-D, hãy thêm đường liên kết đến đề xuất kiểm thử mà bạn đã tạo trong Công cụ theo dõi lỗi của Google trong quy trình gửi CTS-D.

Tạo kế hoạch phụ

Ví dụ: bạn có thể thêm tệp SubPlan.xml trong android-cts/subplans như sau:

<?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>

Cách chạy kế hoạch phụ:

run cts --subplan aSubPlan

Định dạng mục nhập của kế hoạch phụ là:

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" />

Tên và vị trí kiểm thử

Hầu hết các trường hợp kiểm thử CTS đều nhắm đến một lớp cụ thể trong API Android. Các chương trình kiểm thử này có tên gói Java có hậu tố cts và tên lớp có hậu tố Test. Mỗi trường hợp kiểm thử bao gồm nhiều bài kiểm thử, trong đó mỗi bài kiểm thử thường thực thi một phương thức cụ thể của lớp đang được kiểm thử. Các chương trình kiểm thử này được sắp xếp theo cấu trúc thư mục, trong đó các chương trình kiểm thử được nhóm thành nhiều danh mục như "tiện ích" hoặc "thành phần hiển thị".

Ví dụ: kiểm thử CTS cho gói Java android.widget.TextView là android.widget.cts.TextViewTest với tên gói Java là android.widget.cts và tên lớp là TextViewTest.

  • Tên gói Java
    Tên gói Java cho các kiểm thử CTS là tên gói của lớp mà kiểm thử đang kiểm thử, theo sau là .cts. Trong ví dụ này, tên gói sẽ là android.widget.cts.
  • Tên lớp
    Tên lớp cho các kiểm thử CTS là tên của lớp đang được kiểm thử, thêm "Kiểm thử" vào sau. Ví dụ: nếu một kiểm thử đang nhắm đến TextView, thì tên lớp phải là TextViewTest.
  • Tên mô-đun (chỉ dành cho CTS v2)
    CTS v2 sắp xếp các bài kiểm thử theo mô-đun. Tên mô-đun thường là chuỗi thứ hai của tên gói Java (trong ví dụ của chúng ta là widget).

Cấu trúc thư mục và mã mẫu phụ thuộc vào việc bạn đang sử dụng CTS v1 hay CTS v2.

CTS phiên bản 1

Đối với Android 6.0 trở xuống, hãy sử dụng CTS phiên bản 1. Đối với CTS phiên bản 1, mã mẫu nằm ở cts/tests/tests/example.

Cấu trúc thư mục trong các bài kiểm thử CTS phiên bản 1 có dạng như sau: 

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

CTS phiên bản 2

Đối với Android 7.0 trở lên, hãy sử dụng CTS v2. Để biết thông tin chi tiết, hãy xem quy trình kiểm thử mẫu trong Dự án nguồn mở Android (AOSP).

Cấu trúc thư mục CTS v2 có dạng như sau: 

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

Gói mẫu mới

Khi thêm kiểm thử mới, có thể không có thư mục hiện có để đặt kiểm thử. Trong những trường hợp đó, bạn cần tạo thư mục và sao chép các tệp mẫu thích hợp.

CTS phiên bản 1

Nếu bạn đang sử dụng CTS phiên bản 1, hãy tham khảo ví dụ trong cts/tests/tests/example và tạo một thư mục mới. Ngoài ra, hãy nhớ thêm tên mô-đun của gói mới từ Android.mk vào CTS_COVERAGE_TEST_CASE_LIST trong cts/CtsTestCaseList.mk. build/core/tasks/cts.mk sử dụng tệp makefile này để kết hợp tất cả các chương trình kiểm thử và tạo gói CTS cuối cùng.

CTS phiên bản 2

Sử dụng chương trình kiểm thử mẫu /cts/tests/sample/ để nhanh chóng bắt đầu mô-đun kiểm thử mới theo các bước sau:

  1. Để tạo thư mục kiểm thử và sao chép tệp mẫu, hãy chạy: 
    mkdir cts/tests/module-name && cp -r cts/tests/sample/* cts/tests/module-name
  2. Chuyển đến cts/tests/module-name và thay thế tất cả các thực thể của "[Ss]ample" bằng quy ước đặt tên được đề xuất ở trên.
  3. Cập nhật SampleDeviceActivity để thực thi tính năng bạn đang kiểm thử.
  4. Cập nhật SampleDeviceTest để đảm bảo hoạt động thành công hoặc ghi lại lỗi.

Thư mục bổ sung

Bạn cũng có thể thêm các thư mục Android khác như assets, jni, libs và res. Để thêm mã JNI, hãy tạo một thư mục trong thư mục gốc của dự án bên cạnh src bằng mã gốc và tệp makefile Android.mk trong đó.

Tệp makefile thường chứa các chế độ cài đặt sau: 

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)

Tệp Android.mk

Cuối cùng, hãy sửa đổi tệp Android.mk trong thư mục gốc của dự án để tạo mã gốc và phụ thuộc vào mã đó, như minh hoạ bên dưới:

# 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))

Khắc phục hoặc xoá kiểm thử

Ngoài việc thêm các chương trình kiểm thử mới, bạn có thể sửa hoặc xoá các chương trình kiểm thử được chú thích bằng BrokenTest hoặc KnownFailure.

Gửi các thay đổi

Khi gửi bản vá CTS hoặc VTS trong AOSP, hãy chọn nhánh phát triển dựa trên cấp độ API mà bản vá áp dụng.

  • Đối với các thay đổi áp dụng cho nhiều cấp độ API, trước tiên, hãy phát triển một bản vá trong aosp/main, sau đó chọn nhánh kiểm thử ngược dòng nhất. Cho phép trình hợp nhất tự động hợp nhất các thay đổi ở hạ nguồn trong các nhánh kiểm thử AOSP. Hãy xem phần Lịch phát hành và thông tin về nhánh để biết danh sách các nhánh và thông tin về đường dẫn tự động hợp nhất.
  • Đối với các thay đổi dành riêng cho một cấp độ API cụ thể, hãy phát triển hoặc chọn lọc các thay đổi cho nhánh kiểm thử chính xác bằng DO NOT MERGE (KHÔNG HỢP NHẬP) hoặc RESTRICT AUTOMERGE (HẠN CHẾ TỰ ĐỘNG HỢP NHẬP) trong thông báo cam kết.

Làm theo quy trình gửi bản vá để đóng góp các thay đổi cho CTS. Chúng tôi sẽ chỉ định một người đánh giá để xem xét nội dung thay đổi của bạn.

Lịch phát hành và thông tin về nhánh

Các bản phát hành CTS tuân theo lịch trình này.

Phiên bản Cấp độ API Chi nhánh Tần suất sao lưu
15 35 android15-tests-dev Hàng quý
14 34 android14-tests-dev Hàng quý
13 33 android13-tests-dev Hàng quý
12L 32 android12L-tests-dev Hàng quý
12 31 android12-tests-dev Hàng quý

Các ngày quan trọng trong quá trình phát hành

  • Kết thúc tuần đầu tiên: Đóng băng mã. Các thay đổi được hợp nhất trong nhánh cho đến khi ngừng cập nhật mã sẽ được xem xét cho phiên bản CTS sắp tới. Các nội dung gửi đến nhánh sau khi ngừng cập nhật mã hoặc sau khi chọn một ứng cử viên phát hành sẽ được xem xét cho bản phát hành tiếp theo.
  • Tuần thứ hai hoặc thứ ba: CTS được phát hành trong AOSP.

Quy trình tự động hợp nhất

Các nhánh phát triển CTS đã được thiết lập để các thay đổi được gửi đến từng nhánh sẽ tự động hợp nhất với các nhánh cao hơn.

Đối với các thay đổi trực tiếp đối với nhánh phát triển kiểm thử AOSP, đường dẫn tự động hợp nhất là:
android11-tests-dev > android12-tests-dev > android12L-tests-dev > android13-tests-dev > android14-tests-dev > android15-tests-dev > aosp-main

Đối với các thay đổi chỉ dành cho phiên bản Android tiếp theo, đường dẫn tự động hợp nhất là:
aosp-main > <Internal git_main>.

Nếu danh sách thay đổi (CL) không hợp nhất chính xác, tác giả của bản vá sẽ nhận được email kèm theo hướng dẫn về cách giải quyết xung đột. Trong hầu hết các trường hợp, tác giả của bản vá có thể sử dụng hướng dẫn để bỏ qua tính năng tự động hợp nhất của CL xung đột.

Nếu một nhánh cũ yêu cầu thay đổi, thì bạn cần chọn một số bản vá từ nhánh mới hơn.