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. Podczas wydawania polecenia repo init określ konkretną gałąź CTS za pomocą polecenia -b. Dzięki temu zmiany w CTS zostaną uwzględnione w kolejnych wersjach CTS.

Poniższy przykładowy kod pokazuje, jak używać 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 utworzyć CTS i uruchomić interaktywną konsolę CTS, wykonaj te polecenia:

Uwaga: możesz użyć właściwości aosp_x86_64 zamiast aosp_arm64.

Kompilowanie pakietu 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 tabelą poniżej:

Oddział	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 oparty na interfejsie API dla deweloperów (CTS-D), musisz najpierw przesłać propozycję testu zgodnie z instrukcjami w procesie przesyłania testów CTS.

Testy CTS korzystają z JUnit i interfejsów API do testowania Androida. Zapoznaj się z samouczkiem Testowanie aplikacji i sprawdź istniejące testy w katalogu cts/tests. Testy CTS w większości przypadków są zgodne z konwencjami stosowanymi w innych testach Androida.

Testy CTS są przeprowadzane na wielu urządzeniach produkcyjnych, więc muszą być zgodne z tymi zasadami:

• Weź pod uwagę 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 widoku lub polegania na wymiarach komponentów, które mogą nie być dostępne na niektórych urządzeniach.
• Nie polegaj na uprawnieniach roota.

Dodawanie adnotacji w Javie

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

Typ interfejsu API	Format adnotacji	Uwagi
Metoda	android.example.ClassA#methodA	Najczęstszy przypadek użycia.
Metoda z wartościami klucza	android.example.ClassB#methodB(KeyA)	Używaj tylko wtedy, gdy test korzysta z 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, w kodzie testu CTS oznacz identyfikator wymagania (w tym identyfikator sekcji CDD i identyfikator wymagania) symbolem @CddTest, jak pokazano w tym przykładzie. W komunikacie dotyczącym zatwierdzenia wspomnij, które wymaganie CDD jest testowane przez Twój test, 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 weryfikatora CTS dodaj do każdego działania w pliku AndroidManifest.xml odpowiedni identyfikator CDD. Formaty pól wartości są podobne do formatów adnotacji Java w CTS. W komentarzu do zatwierdzenia wspomnij, które wymaganie CDD jest egzekwowane, odwołując się do identyfikatora wymagania 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>

W komunikacie zatwierdzenia

Wyraźnie podaj powód dodania testu i dodaj odpowiednie linki do pomocy. W przypadku testów CTS-D podaj link do propozycji testu utworzonej w Google Issue Tracker w ramach procesu przesyłania CTS-D.

Tworzenie pakietu podrzędnego

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ć subplan:

run cts --subplan aSubPlan

Format wpisu dotyczącego subskrypcji to:

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

Nazwa i lokalizacja testu

Większość przypadków testowych CTS jest ukierunkowana na konkretną klasę w interfejsie Android API. Te testy 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 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, a jego 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 w przypadku testów CTS to nazwa testowanej klasy z dodanym słowem „Test”. Jeśli na przykład test jest kierowany na TextView, nazwa klasy powinna brzmieć TextViewTest.
• Nazwa modułu (tylko CTS w wersji 2)
  CTS w wersji 2 porządkuje testy według modułów. Nazwa modułu to zwykle drugi ciąg znaków nazwy pakietu Java (w naszym przykładzie widget).

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

CTS w wersji 1

W przypadku Androida 6.0 lub starszego użyj CTS w wersji 1. W przypadku CTS w wersji 1 przykładowy kod znajdziesz na stronie cts/tests/tests/example.

Struktura katalogów w testach CTS w wersji 1 wygląda tak:

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

CTS w wersji 2

W przypadku Androida 7.0 lub nowszego użyj CTS w wersji 2. Więcej informacji znajdziesz w przykładzie testu w projekcie Android Open Source Project (AOSP).

Struktura katalogu CTS w wersji 2 wygląda tak:

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

Nowe pakiety próbek

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

CTS w wersji 1

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

CTS w wersji 2

Aby szybko rozpocząć korzystanie z nowego modułu testowego, wykonaj te czynności: /cts/tests/sample/

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

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

2. Otwórz cts/tests/module-name i zastąp wszystkie wystąpienia ciągu „[Ss]ample” zalecaną konwencją nazewnictwa podaną powyżej.
3. Zaktualizuj urządzenie SampleDeviceActivity, aby przetestować funkcję.
4. Zaktualizuj SampleDeviceTest, aby zapewnić powodzenie działania lub rejestrowanie błędów.

Dodatkowe katalogi

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

Plik makefile zawiera zwykle 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 utworzyć 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 i usuwanie testów

Oprócz dodawania nowych testów możesz też poprawiać lub usuwać testy oznaczone ikoną BrokenTest lub KnownFailure.

Wprowadzanie zmian

Podczas przesyłania zmian do CTS postępuj zgodnie z procedurą Przesyłanie zmian w kodzie.

• Wybierz gałąź deweloperską na podstawie poziomów interfejsu API, do których ma zastosowanie poprawka.
• Wprowadź zmiany w odpowiedniej gałęzi testowej lub wybierz je z innej gałęzi, a w komentarzu do zatwierdzenia użyj DO NOT MERGE lub RESTRICT AUTOMERGE.

Osoba weryfikująca sprawdzi Twoją zmianę i wybierze ją do wewnętrznego systemu Gerrit.

Harmonogram udostępniania i informacje o gałęzi

Wydania CTS są zgodne z tym harmonogramem.

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

Wersja	Poziom interfejsu 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ł
13	33	android13-tests-dev	Co kwartał

Uwaga: nie planujemy kolejnych wersji od 4.2 do 12.1.

Ważne daty podczas premiery

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

Procedura automatycznego scalania

Gałęzie deweloperskie CTS zostały skonfigurowane tak, aby zmiany przesyłane do każdej z nich były automatycznie scalane z gałęziami wyższego poziomu.

W przypadku zmian wprowadzanych bezpośrednio w gałęzi deweloperskiej testów AOSP ścieżka automatycznego scalania wygląda tak:
android13-tests-dev > android14-tests-dev > android15-tests-dev

• W przypadku wersji CTS 16 i nowszych osoba sprawdzająca wybierze zmianę i odpowiednio wprowadzi ją do wewnętrznego systemu Gerrit.

Jeśli lista zmian nie zostanie prawidłowo scalona, autor poprawki otrzyma e-maila z instrukcjami rozwiązania konfliktu. W większości przypadków autor poprawki może skorzystać z tych instrukcji, aby pominąć automatyczne scalanie powodującego konflikt CL.

Jeśli starsza gałąź wymaga zmiany, należy przenieść poprawkę z nowszej gałęzi.

W przypadku zmian testowych dotyczących następnej wersji Androida po przesłaniu proponowanej zmiany Google ją sprawdza i w razie akceptacji wybiera ją do wewnętrznego systemu Gerrit.