Rozwój CTS

Inicjowanie klienta Repo

Aby pobrać i skompilować kod źródłowy Androida, postępuj zgodnie z instrukcjami w sekcji Pobieranie kodu źródłowego. Gdy wydajesz polecenie repo init, użyj flagi -b, aby określić konkretną gałąź CTS. Dzięki temu zmiany w CTS zostaną uwzględnione w kolejnych wersjach CTS.

Poniższy przykładowy kod pokazuje, jak używać polecenia 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

Kompilowanie i uruchamianie CTS

Aby skompilować CTS i uruchomić interaktywną konsolę CTS, wykonaj te polecenia:

Uwaga: zamiast aosp_arm64 możesz użyć aosp_x86_64.

Kompilowanie CTS (AOSP 14 lub starszy)

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

Kompilowanie 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

Aby wybrać wartość target-release, zapoznaj się z tą tabelą:

Gałąź	Wersja docelowa
android15-tests-dev	ap3a

Uruchamianie CTS

W konsoli CTS wpisz:

tf> run cts --plan CTS

Pisanie testów CTS

Aby napisać test CTS-D (CTS dla programistów), musisz najpierw przesłać propozycję testu zgodnie z instrukcjami w sekcji Proces przesyłania CTS.

Testy CTS korzystają z JUnit i interfejsów API testowania Androida. Zapoznaj się z samouczkiem Testowanie aplikacji i istniejącymi testami w katalogu cts/tests. Testy CTS w większości przypadków są zgodne z tymi samymi konwencjami, które są używane w innych testach Androida.

CTS działa na wielu urządzeniach produkcyjnych, dlatego testy muszą być zgodne z tymi regułami:

• Uwzględniaj różne rozmiary ekranu, orientacje i układy klawiatury.
• Używaj tylko publicznych metod interfejsu API. Innymi słowy, unikaj wszystkich klas, metod i pól z adnotacją hide.
• Unikaj używania układów widoków i polegania na wymiarach zasobów, które mogą nie być dostępne na niektórych urządzeniach.
• Nie polegaj na uprawnieniach roota.

Dodawanie adnotacji Java

Jeśli test weryfikuje działanie interfejsu API, dodaj do kodu testu adnotację @ApiTest i wymień wszystkie interfejsy API w polu apis. Użyj odpowiedniego formatu z tych przykładów:

Typ interfejsu API	Format adnotacji	Uwagi
Metoda	android.example.ClassA#methodA	Najczęstszy przypadek użycia.
Metoda z parami klucz-wartość	android.example.ClassB#methodB(KeyA)	Używaj tylko wtedy, gdy test używa metody interfejsu API do weryfikacji pola, jak w tym przykładzie.
Pole	android.example.ClassC#FieldA	Używaj tylko wtedy, gdy test bezpośrednio weryfikuje pole interfejsu API, jak w tym przykładzie.

Jeśli test weryfikuje wymaganie CDD, dodaj do kodu testu CTS adnotację @CddTest z identyfikatorem wymagania (w tym identyfikatorem sekcji CDD i identyfikatorem wymagania), jak pokazano w tym przykładzie. W komunikacie zatwierdzenia wspomnij, które wymaganie CDD jest testowane, odwołując się do identyfikatorów wymagań CDD. Identyfikatory wymagań CDD to połączenie identyfikatora sekcji i identyfikatora wymagania, połączonych ukośnikiem (/), np. 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()));
    }

W przypadku CTS Verifier dodaj do każdej aktywności w pliku AndroidManifest.xml odpowiedni identyfikator CDD. Formaty pól wartości są podobne do formatów adnotacji Java w CTS. W komunikacie zatwierdzenia wspomnij, które wymaganie CDD jest egzekwowane, odwołując się do identyfikatora wymagania CDD wymagania.

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

W komunikacie zatwierdzenia

Wyraźnie wyjaśnij, dlaczego należy dodać test, i dodaj odpowiednie linki do pomocy. W przypadku testów CTS-D dodaj link do propozycji testu utworzonej w narzędziu Google Issue Tracker w ramach procesu przesyłania CTS-D CTS-D.

Tworzenie podplanu

Możesz na przykład dodać plik SubPlan.xml w android-cts/subplans w ten sposób:

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

Aby uruchomić podplan:

run cts --subplan aSubPlan

Format wpisu podplanu:

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

Nazewnictwo i lokalizacja testów

Większość przypadków testowych CTS jest kierowana na konkretną klasę w interfejsie API Androida. Testy te mają nazwy pakietów Java z sufiksem cts i nazwy klas z sufiksem Test. Każdy przypadek testowy składa się z wielu testów, z których każdy zwykle sprawdza konkretną metodę testowanej klasy. Testy te są ułożone w strukturze katalogów, w której są pogrupowane w różne kategorie, np. „widżety” lub „widoki”.

Na przykład test CTS dla pakietu Java android.widget.TextView to android.widget.cts.TextViewTest, którego nazwa pakietu Java to android.widget.cts, a nazwa klasy to TextViewTest.

• Nazwa pakietu Java
  Nazwa pakietu Java dla testów CTS to nazwa pakietu klasy, którą testuje test, a po niej następuje .cts. W naszym przykładzie nazwa pakietu to android.widget.cts.
• Nazwa klasy
  Nazwa klasy dla testów CTS to nazwa testowanej klasy z dodanym sufiksem „Test”. Jeśli na przykład test jest kierowany na TextView, nazwa klasy powinna brzmieć TextViewTest.
• Nazwa modułu (tylko CTS v2)
  CTS v2 porządkuje testy według modułów. Nazwa modułu jest zwykle drugim ciągiem nazwy pakietu Java (w naszym przykładzie widget).

Struktura katalogów i przykładowy kod zależą od tego, czy używasz CTS v1 czy CTS v2.

CTS v1

W przypadku Androida 6.0 lub starszego użyj CTS v1. W przypadku CTS v1 przykładowy kod znajduje się w cts/tests/tests/example.

Struktura katalogów w testach CTS v1 wygląda tak:

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

CTS v2

W przypadku Androida 7.0 lub nowszego użyj CTS v2. Więcej informacji znajdziesz w przykładowym teście w projekcie Android Open Source (AOSP).

Struktura katalogów CTS v2 wygląda tak:

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

Nowe przykładowe pakiety

Podczas dodawania nowych testów może nie być istniejącego katalogu, w którym można umieścić test. W takich przypadkach musisz utworzyć katalog i skopiować odpowiednie przykładowe pliki.

CTS v1

Jeśli używasz CTS v1, zapoznaj się z przykładem w cts/tests/tests/example i utwórz nowy katalog. Dodaj też nazwę modułu nowego pakietu z pliku Android.mk do CTS_COVERAGE_TEST_CASE_LIST w cts/CtsTestCaseList.mk. build/core/tasks/cts.mk używa tego pliku makefile do łączenia wszystkich testów i tworzenia końcowego pakietu CTS.

CTS v2

Aby szybko rozpocząć nowy moduł testowy, wykonaj te czynności, korzystając z przykładowego testu /cts/tests/sample/ :

1. Aby utworzyć katalog testowy i skopiować przykładowe pliki, uruchom:

   mkdir cts/tests/module-name && cp -r cts/tests/sample/* cts/tests/module-name

2. Przejdź do cts/tests/module-name i zastąp wszystkie wystąpienia "[Ss]ample" zalecaną konwencją nazewnictwa opisaną powyżej.
3. Zaktualizuj SampleDeviceActivity, aby sprawdzić testowaną funkcję.
4. Zaktualizuj SampleDeviceTest, aby mieć pewność, że aktywność zakończy się powodzeniem lub zarejestruje błędy.

Dodatkowe katalogi

Możesz też dodać inne katalogi Androida, takie jak assets, jni, libs i res. Aby dodać kod JNI, utwórz katalog w katalogu głównym projektu obok src z kodem natywnym i plikiem makefile Android.mk.

Plik makefile zwykle zawiera te ustawienia:

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)

Plik Android.mk

Na koniec zmodyfikuj plik Android.mk w katalogu głównym projektu, aby skompilować kod natywny i od niego zależeć, jak pokazano poniżej:

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

Naprawianie lub usuwanie testów

Oprócz dodawania nowych testów możesz też naprawiać lub usuwać testy z adnotacjami BrokenTest lub KnownFailure.

Przesyłanie zmian

Podczas przesyłania zmian do CTS postępuj zgodnie z procesem przesyłania zmian kodu.

• Wybierz gałąź programistyczną na podstawie poziomów interfejsu API, do których ma zastosowanie poprawka.
• Opracuj lub przenieś zmiany do odpowiedniej gałęzi testowej z DO NOT MERGE lub RESTRICT AUTOMERGE w komunikacie zatwierdzenia.

Odbiorca zostanie przypisany do sprawdzenia zmiany i przeniesienia jej do wewnętrznego Gerrit.

Harmonogram publikacji i informacje o gałęziach

Wersje CTS są udostępniane zgodnie z tym harmonogramem.

Uwaga: ten harmonogram jest tymczasowy i będzie aktualizowany w miarę rozwoju CTS dla danej wersji Androida.

Wersja	Poziom API	Gałąź programistyczna	Częstotliwość publikacji
16+	36+	Wewnętrzny Gerrit	Co kwartał
15	35	android15-tests-dev	Co kwartał
14	34	android14-tests-dev	Co kwartał

Uwaga: nie planujemy udostępniania kolejnych wersji od 4.2 do 13.

Ważne daty podczas udostępniania

• Koniec pierwszego tygodnia: zamrożenie kodu. Zmiany scalone w gałęzi do momentu zamrożenia kodu są uwzględniane w nadchodzącej wersji CTS. Przesłane do gałęzi po zamrożeniu kodu lub po wybraniu wersji kandydującej do udostępnienia są uwzględniane w kolejnej wersji.
• Drugi lub trzeci tydzień: CTS jest publikowany na stronie pobierania pakietu Compatibility Test Suite.

Proces automatycznego scalania

Gałęzie programistyczne CTS zostały skonfigurowane tak, aby zmiany przesyłane do każdej gałęzi były automatycznie scalane z gałęziami wyższymi.

W przypadku zmian bezpośrednio w gałęzi programistycznej testów AOSP ścieżka automatycznego scalania to:
android13-tests-dev > android14-tests-dev > android15-tests-dev

• W przypadku wersji CTS 16+ odbiorca przeniesie zmianę do wewnętrznego Gerrit.

Jeśli scalenie listy zmian (CL) nie powiedzie się, autor poprawki otrzyma e-maila z instrukcjami, jak rozwiązać konflikt. W większości przypadków autor poprawki może skorzystać z instrukcji, aby pominąć automatyczne scalanie powodującej konflikt listy zmian.

Jeśli zmiana jest wymagana w starszej gałęzi, poprawkę należy przenieść z nowszej gałęzi.

W przypadku zmian testowych mających zastosowanie do następnej wersji Androida po przesłaniu proponowanej zmiany, Google ją sprawdzi i, jeśli zostanie zaakceptowana, przeniesie ją do wewnętrznego Gerrit.