Développement CTS

Initialiser votre client Repo

Suivez les instructions de la section Télécharger le code source pour obtenir et compiler le code source Android. Lorsque vous exécutez la commande repo init, spécifiez une branche CTS spécifique à l'aide de -b. Cela garantit que vos modifications CTS sont incluses dans les versions CTS ultérieures.

L'exemple de code suivant montre comment utiliser repo init.

Compiler et exécuter CTS

Exécutez les commandes suivantes pour créer CTS et démarrer la console CTS interactive:

Créer CTS (AOSP 14 ou version antérieure)

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

Compiler le CTS (AOSP 15 ou version ultérieure)

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

Reportez-vous au tableau suivant pour sélectionner la valeur target-release:

Dans la console CTS, saisissez:

tf> run cts --plan CTS

Écrire des tests CTS

Les tests CTS utilisent JUnit et les API de test Android. Consultez le tutoriel sur le test de votre application et les tests existants dans le répertoire cts/tests. Les tests CTS suivent principalement les mêmes conventions que les autres tests Android.

Le CTS s'exécute sur de nombreux appareils de production. Les tests doivent donc respecter les règles suivantes:

• Tenez compte des différentes tailles d'écran, orientations et dispositions de clavier.
• N'utilisez que les méthodes d'API publiques. En d'autres termes, évitez toutes les classes, méthodes et champs avec l'annotation hide.
• Évitez d'utiliser des mises en page de vue ou de vous appuyer sur les dimensions d'éléments qui ne se trouvent peut-être pas sur certains appareils.
• Ne vous fiez pas aux droits racine.

Ajouter une annotation Java

Si votre test vérifie un comportement d'API, annotez votre code de test avec @ApiTest et listez toutes les API impliquées dans le champ apis. Utilisez le format approprié parmi les exemples suivants:

Si votre test vérifie une exigence du CDD, annotez l'ID de l'exigence (y compris l'ID de la section du CDD et l'ID de l'exigence) avec @CddTest dans le code de test CTS, comme illustré dans l'exemple suivant. Dans le message de votre commit, indiquez la ou les exigences de la CDD testées par votre test en vous référant aux ID des exigences de la CDD. Les ID de l'exigence de la CDD sont une combinaison de l'ID de la section et de l'ID de l'exigence, reliés par un slash (/), comme dans 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()));
    }

Pour le vérificateur CTS, annotez chaque activité de votre AndroidManifest.xml avec l'ID CDD approprié. Les formats des champs de valeur sont similaires aux formats des annotations Java dans le CTS. Dans le message de commit, indiquez quelle exigence du CDD est appliquée en référençant l'ID de l'exigence du 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>

Dans le message de commit

Indiquez clairement pourquoi votre test doit être ajouté et ajoutez des liens pertinents pour obtenir de l'aide. Pour les tests CTS-D, incluez un lien vers la proposition de test que vous avez créée dans l'outil de suivi des problèmes de Google dans le cadre du processus d'envoi des tests CTS-D.

Créer un sous-plan

Par exemple, vous pouvez ajouter un fichier SubPlan.xml dans android-cts/subplans comme suit:

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

Pour exécuter le sous-plan:

run cts --subplan aSubPlan

Le format d'entrée du sous-plan est le suivant:

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

Nom et emplacement du test

La plupart des scénarios de test CTS ciblent une classe spécifique de l'API Android. Ces tests ont des noms de packages Java avec un suffixe cts et des noms de classe avec un suffixe Test. Chaque scénario de test se compose de plusieurs tests, chacun exerçant généralement une méthode spécifique de la classe testée. Ces tests sont organisés dans une structure de répertoires, où ils sont regroupés dans différentes catégories telles que "widgets" ou "vues".

Par exemple, le test CTS du package Java android.widget.TextView est android.widget.cts.TextViewTest, avec le nom du package Java android.widget.cts et le nom de classe TextViewTest.

• Nom de package Java
  Le nom de package Java des tests CTS correspond au nom de package de la classe testée, suivi de .cts. Dans notre exemple, le nom du package est android.widget.cts.
• Nom de la classe
  Le nom de la classe pour les tests CTS est le nom de la classe testée, suivi de "Test". Par exemple, si un test cible TextView, le nom de la classe doit être TextViewTest.
• Nom du module (CTS v2 uniquement)
  CTS v2 organise les tests par module. Le nom du module correspond généralement à la deuxième chaîne du nom du package Java (widget dans notre exemple).

La structure de répertoire et l'exemple de code dépendent de l'utilisation de la version 1 ou de la version 2 de CTS.

CTS v1

Pour Android 6.0 ou version antérieure, utilisez la version 1 du CTS. Pour la version 1 de CTS, l'exemple de code se trouve dans cts/tests/tests/example.

La structure de répertoire des tests CTS v1 se présente comme suit:

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

CTS v2

Pour Android 7.0 ou version ultérieure, utilisez CTS v2. Pour en savoir plus, consultez l'exemple de test dans le projet Android Open Source (AOSP).

La structure de répertoires de CTS v2 se présente comme suit:

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

Nouveaux packages d'exemples

Lorsque vous ajoutez des tests, il est possible qu'il n'existe pas de répertoire dans lequel les placer. Dans ce cas, vous devez créer le répertoire et copier les exemples de fichiers appropriés.

CTS v1

Si vous utilisez la version 1 de CTS, consultez l'exemple sous cts/tests/tests/example et créez un répertoire. Assurez-vous également d'ajouter le nom du module de votre nouveau package de Android.mk à CTS_COVERAGE_TEST_CASE_LIST dans cts/CtsTestCaseList.mk. build/core/tasks/cts.mk utilise ce fichier make pour combiner tous les tests et créer le package CTS final.

CTS v2

Utilisez l'exemple de test /cts/tests/sample/ pour démarrer rapidement votre nouveau module de test en procédant comme suit:

1. Pour créer le répertoire de test et copier les exemples de fichiers, exécutez la commande suivante:

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

2. Accédez à cts/tests/module-name et remplacez toutes les instances de "[Ss]ample" par la convention de dénomination recommandée ci-dessus.
3. Mettez à jour SampleDeviceActivity pour utiliser la fonctionnalité que vous testez.
4. Mettez à jour SampleDeviceTest pour vous assurer que l'activité aboutit ou consigne ses erreurs.

Répertoires supplémentaires

Vous pouvez également ajouter d'autres répertoires Android tels que assets, jni, libs et res. Pour ajouter du code JNI, créez un répertoire dans la racine du projet à côté de src avec le code natif et un fichier de compilation Android.mk.

Le fichier makefile contient généralement les paramètres suivants:

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)

Fichier Android.mk

Enfin, modifiez le fichier Android.mk dans la racine du projet pour compiler le code natif et en dépendre, comme indiqué ci-dessous:

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

Corriger ou supprimer des tests

En plus d'ajouter de nouveaux tests, vous pouvez corriger ou supprimer des tests annotés avec BrokenTest ou KnownFailure.

Envoyer les modifications

Lorsque vous envoyez des correctifs CTS ou VTS dans AOSP, choisissez votre branche de développement en fonction des niveaux d'API auxquels le correctif s'applique.

• Pour les modifications qui s'appliquent à plusieurs niveaux d'API, d'abord développez un correctif dans aosp/main, puis sélectionnez les modifications à appliquer à la branche de test la plus en amont. Autorisez la fusion automatique à fusionner les modifications en aval dans les branches de test AOSP. Pour obtenir la liste des branches et des informations sur le chemin d'autofusion, consultez la section Calendrier de publication et informations sur les branches.
• Pour les modifications spécifiques à un niveau d'API spécifique, développez ou sélectionnez les modifications à apporter à la branche de test appropriée avec DO NOT MERGE ou RESTRICT AUTOMERGE dans le message de commit.

Suivez le workflow d'envoi des correctifs pour apporter des modifications à CTS. Un examinateur sera désigné pour examiner votre modification en conséquence.

Calendrier de publication et informations sur la branche

Les versions du CTS respectent ce calendrier.

Dates importantes pendant la publication

• Fin de la première semaine:gel du code. Les modifications fusionnées dans la branche jusqu'au gel du code sont prises en compte pour la prochaine version de CTS. Les envois à la branche après le gel du code ou après le choix d'un candidat à la publication sont pris en compte pour la version suivante.
• Deuxième ou troisième semaine:le CTS est publié dans AOSP.

Flux de fusion automatique

Les branches de développement CTS ont été configurées de sorte que les modifications envoyées à chaque branche soient automatiquement fusionnées dans les branches supérieures.

Pour les modifications apportées directement à une branche de développement de test AOSP, le chemin d'autofusion est le suivant:
android11-tests-dev > android12-tests-dev > android12L-tests-dev > android13-tests-dev > android14-tests-dev > android15-tests-dev > aosp-main

Pour les modifications apportées uniquement à la prochaine version d'Android, le chemin d'autofusion est le suivant:
aosp-main > <Internal git_main>.

Si la fusion d'une liste de modifications (CL) ne fonctionne pas correctement, un e-mail est envoyé à l'auteur du correctif avec des instructions pour résoudre le conflit. Dans la plupart des cas, l'auteur du correctif peut utiliser les instructions pour ignorer la fusion automatique du CL en conflit.

Si une branche plus ancienne nécessite la modification, le correctif doit être sélectionné dans la branche plus récente.