توسعه CTS

مشتری Repo خود را راه اندازی کنید

دستورالعمل های دانلود منبع را برای دریافت و ساخت کد منبع اندروید دنبال کنید. هنگام صدور دستور repo init ، یک شاخه CTS خاص را با استفاده از -b مشخص کنید. این تضمین می کند که تغییرات 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 اجرا کنید:

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

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

tf> run cts --plan CTS

تست های CTS را بنویسید

تست های CTS از JUnit و API های تست اندروید استفاده می کنند. آموزش تست برنامه خود و تست های موجود را در فهرست cts/tests مرور کنید. تست‌های CTS عمدتاً از همان قراردادهای مورد استفاده در سایر تست‌های اندروید پیروی می‌کنند.

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

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

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

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

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

اگر آزمون شما یک نیاز CDD را تأیید کرد، شناسه الزامی (شامل شناسه بخش CDD و شناسه الزامی) را با @CddTest در کد آزمون CTS همانطور که در مثال زیر نشان داده شده است، حاشیه نویسی کنید. در پیام commit خود، با مراجعه به شناسه های نیازمندی 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 است. در پیام commit، با ارجاع به شناسه الزام 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>

در پیام commit

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

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

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

ساختار دایرکتوری و کد نمونه بستگی به این دارد که آیا از CTS v1 یا CTS v2 استفاده می کنید.

CTS v1

برای اندروید ۶.۰ یا پایین‌تر، از CTS نسخه ۱ استفاده کنید. برای 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 نسخه 2

برای 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_COVERAGE_TEST_CASE_LIST در cts/CtsTestCaseList.mk اضافه کنید. build/core/tasks/cts.mk از این makefile برای ترکیب تمامی تست ها و ایجاد بسته نهایی 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 به روز کنید تا مطمئن شوید که فعالیت موفق است یا خطاهای خود را ثبت می کند.

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

فهرست های دیگر اندروید مانند assets ، jni ، libs و res نیز می توانند اضافه شوند. برای افزودن کد JNI، یک دایرکتوری در ریشه پروژه در کنار src با کد بومی و یک فایل ساخت 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 را در ریشه پروژه تغییر دهید تا کد بومی ساخته شود و به آن وابسته شود، مانند شکل زیر:

# 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 ایجاد کنید و سپس به بالادست ترین شاخه آزمایشی انتخاب کنید. به Automerger اجازه دهید تا تغییرات پایین دستی را در شاخه های آزمایشی AOSP ادغام کند. برای لیست شعب و اطلاعات مسیر ادغام خودکار، برنامه زمان بندی انتشار و اطلاعات شعب را ببینید.
  • برای تغییراتی که مختص یک سطح API خاص هستند، تغییرات را در شاخه آزمایشی صحیح با DO NOT MERGE یا RESTRICT AUTOMERGE در پیام commit ایجاد کنید یا انتخاب کنید.

برای ایجاد تغییرات در CTS ، گردش کار ارسال وصله ها را دنبال کنید. یک بازبین منصوب می شود تا تغییرات شما را بر این اساس بررسی کند.

زمان بندی انتشار و اطلاعات شعبه

انتشار CTS از این برنامه پیروی می کند.

نسخه سطح API شاخه فرکانس
14 34 android14-tests-dev سه ماه یکبار
13 33 android13-tests-dev سه ماه یکبار
12 لیتر 32 android12L-tests-dev سه ماه یکبار
12 31 android12-tests-dev سه ماه یکبار
11 30 android11-tests-dev سه ماه یکبار
هیچ نسخه دیگری برای نسخه های 10.0، 9.0، 8.1، 8.0، 7.1، 7.0، 6.0، 5.1، 5.0، 4.4، 4.3 و 4.2 برنامه ریزی نشده است.

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

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

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

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

برای تغییرات مستقیم به یک شاخه توسعه دهنده آزمایشی AOSP، مسیر automerge به صورت زیر است:
android11-tests-dev > android12-tests-dev android12L-tests-dev > android13-tests-dev > android14-tests-dev > aosp/main

برای تغییرات فقط به نسخه اندروید بعدی، مسیر automerge به صورت زیر است:
aosp/main > <Internal git/main> .

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

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