توسعه CTS

کلاینت Repo خود را راه‌اندازی اولیه کنید

برای دریافت و ساخت کد منبع اندروید، دستورالعمل‌های «دانلود منبع» را دنبال کنید. هنگام صدور دستور 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 ، لطفاً به جدول زیر مراجعه کنید:

شعبه انتشار هدف
android15-tests-dev آپ3آ

اجرای CTS

در کنسول CTS، وارد کنید:

tf> run cts --plan CTS

نوشتن تست‌های CTS

تست‌های CTS از JUnit و APIهای تست اندروید استفاده می‌کنند. آموزش Test your app و تست‌های موجود در دایرکتوری cts/tests را مرور کنید. تست‌های CTS اکثراً از همان قراردادهایی که در سایر تست‌های اندروید استفاده می‌شود، پیروی می‌کنند.

CTS در بسیاری از دستگاه‌های تولیدی اجرا می‌شود، بنابراین آزمایش‌ها باید از این قوانین پیروی کنند:

  • اندازه‌های مختلف صفحه نمایش، جهت‌گیری‌ها و طرح‌بندی‌های مختلف صفحه کلید را در نظر بگیرید.
  • فقط از متدهای عمومی API استفاده کنید. به عبارت دیگر، از تمام کلاس‌ها، متدها و فیلدهایی که دارای علامت hide هستند، اجتناب کنید.
  • از استفاده از طرح‌بندی‌های نمایشی یا تکیه بر ابعاد داده‌هایی که ممکن است در برخی دستگاه‌ها وجود نداشته باشند، خودداری کنید.
  • به امتیازات ریشه (root) تکیه نکنید.

اضافه کردن حاشیه‌نویسی جاوا

اگر تست شما رفتار یک API را تأیید می‌کند، کد تست خود را با @ApiTest حاشیه‌نویسی کنید و تمام APIهای درگیر در فیلد apis را فهرست کنید. از قالب مناسب از بین مثال‌های زیر استفاده کنید:

نوع API قالب حاشیه‌نویسی یادداشت‌ها
روش android.example.ClassA#methodA رایج‌ترین مورد استفاده.
متد با مقادیر کلیدی android.example.ClassB#methodB(KeyA) فقط زمانی استفاده کنید که آزمون شما از یک متد API برای اعتبارسنجی یک فیلد استفاده می‌کند، مانند این مثال.
میدان android.example.ClassC#FieldA فقط زمانی استفاده کنید که تست شما مستقیماً یک فیلد API را اعتبارسنجی می‌کند، مانند این مثال.

اگر تست شما یک الزام 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، هر فعالیت را در AndroidManifest.xml خود با شناسه CDD مربوطه حاشیه‌نویسی کنید. قالب‌های فیلدهای مقدار مشابه قالب‌های حاشیه‌نویسی‌های جاوا در 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 یک کلاس خاص در API اندروید را هدف قرار می‌دهند. این تست‌ها دارای نام بسته‌های جاوا با پسوند cts و نام کلاس‌ها با پسوند Test هستند. هر مورد تست شامل چندین تست است که در آن هر تست معمولاً یک متد خاص از کلاس مورد آزمایش را اجرا می‌کند. این تست‌ها در یک ساختار دایرکتوری مرتب شده‌اند که در آن تست‌ها به دسته‌های مختلفی مانند "widgets" یا "views" گروه‌بندی می‌شوند.

برای مثال، آزمون CTS برای بسته جاوا android.widget.TextView android.widget.cts.TextViewTest است که نام بسته جاوای آن android.widget.cts و نام کلاس آن TextViewTest است.

  • نام بسته جاوا
    نام بسته جاوا برای تست‌های CTS، نام بسته کلاسی است که تست در حال آزمایش آن است و به دنبال آن .cts می‌آید. برای مثال ما، نام بسته android.widget.cts خواهد بود.
  • نام کلاس
    نام کلاس برای آزمون‌های CTS، نام کلاسی است که با پسوند "Test" مورد آزمایش قرار می‌گیرد. برای مثال، اگر آزمونی TextView هدف قرار می‌دهد، نام کلاس باید TextViewTest باشد.
  • نام ماژول (فقط CTS نسخه ۲)
    CTS نسخه ۲ تست‌ها را بر اساس ماژول سازماندهی می‌کند. نام ماژول معمولاً رشته دوم نام بسته جاوا (در مثال ما، widget ) است.

ساختار دایرکتوری و کد نمونه بستگی به این دارد که آیا از CTS نسخه ۱ یا CTS نسخه ۲ استفاده می‌کنید.

سی تی اس نسخه ۱

برای اندروید ۶.۰ یا پایین‌تر، از CTS نسخه ۱ استفاده کنید. برای CTS نسخه ۱، کد نمونه در cts/tests/tests/example قرار دارد.

ساختار دایرکتوری در تست‌های CTS نسخه ۱ به این شکل است:

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

سی تی اس نسخه ۲

برای اندروید ۷.۰ یا بالاتر، از CTS نسخه ۲ استفاده کنید. برای جزئیات بیشتر، به نمونه تست در پروژه متن‌باز اندروید (AOSP) مراجعه کنید.

ساختار دایرکتوری CTS v2 به این شکل است: 

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

بسته‌های نمونه جدید

هنگام اضافه کردن تست‌های جدید، ممکن است دایرکتوری موجود برای قرار دادن تست شما وجود نداشته باشد. در این موارد، باید دایرکتوری را ایجاد کرده و فایل‌های نمونه مناسب را کپی کنید.

سی تی اس نسخه ۱

اگر از CTS نسخه ۱ استفاده می‌کنید، به مثال زیر در cts/tests/tests/example مراجعه کنید و یک دایرکتوری جدید ایجاد کنید. همچنین، مطمئن شوید که نام ماژول بسته جدید خود را از Android.mk به CTS_COVERAGE_TEST_CASE_LIST در cts/CtsTestCaseList.mk اضافه کنید. build/core/tasks/cts.mk از این makefile برای ترکیب تمام تست‌ها و ایجاد بسته نهایی CTS استفاده می‌کند.

سی تی اس نسخه ۲

برای شروع سریع ماژول آزمایشی جدید خود با مراحل زیر، از فایل /cts/tests/sample/ نمونه استفاده کنید:

  1. برای ایجاد دایرکتوری test و کپی کردن فایل‌های نمونه، دستور زیر را اجرا کنید: 
    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 را به‌روزرسانی کنید تا از موفقیت‌آمیز بودن فعالیت یا ثبت خطاهای آن اطمینان حاصل شود.

دایرکتوری‌های اضافی

سایر دایرکتوری‌های اندروید مانند 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)

فایل اندروید.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 شاخه توسعه فرکانس انتشار
۱۶+ ۳۶+ گریت داخلی فصلنامه
۱۵ ۳۵ android15-tests-dev فصلنامه
۱۴ ۳۴ android14-tests-dev فصلنامه
۱۳ ۳۳ android13-tests-dev فصلنامه

تاریخ‌های مهم در طول انتشار

  • پایان هفته اول: فریز شدن کد. تغییراتی که تا زمان فریز شدن کد در شاخه ادغام می‌شوند، برای نسخه بعدی CTS در نظر گرفته می‌شوند. ارسال‌ها به شاخه پس از فریز شدن کد یا پس از انتخاب یک نامزد برای انتشار، برای انتشار بعدی در نظر گرفته می‌شوند.
  • هفته دوم یا سوم: CTS در صفحه دانلودهای مجموعه تست سازگاری منتشر می‌شود.

جریان ادغام خودکار

شاخه‌های توسعه CTS طوری تنظیم شده‌اند که تغییرات ارسالی به هر شاخه به طور خودکار در شاخه‌های بالاتر ادغام شوند.

برای تغییرات مستقیم در یک شاخه توسعه آزمایشی AOSP، مسیر ادغام خودکار به صورت زیر است:
android13-tests-dev > android14-tests-dev > android15-tests-dev

  • برای نسخه‌های CTS 16+، یک بررسی‌کننده، تغییرات را بر اساس آن در Gerrit داخلی انتخاب خواهد کرد.

اگر یک لیست تغییرات (CL) به درستی ادغام نشود، برای نویسنده‌ی پچ، ایمیلی حاوی دستورالعمل‌هایی در مورد نحوه‌ی حل تداخل ارسال می‌شود. در بیشتر موارد، نویسنده‌ی پچ می‌تواند از دستورالعمل‌ها برای رد کردن ادغام خودکار CL تداخل‌کننده استفاده کند.

اگر یک شاخه قدیمی‌تر نیاز به تغییر داشته باشد، باید پچ از شاخه جدیدتر انتخاب شود.

برای تغییرات آزمایشی که برای نسخه بعدی اندروید اعمال می‌شوند، پس از آپلود تغییر پیشنهادی، گوگل آن را بررسی می‌کند و در صورت پذیرفته شدن، آن را به Gerrit داخلی اضافه می‌کند.