Exécuter des tests (Atest)

Atest est un outil de ligne de commande qui permet aux utilisateurs de créer, d'installer et d'exécuter des tests Android localement, accélérant considérablement les réexécutions de tests sans nécessiter de connaissance des options de ligne de commande du faisceau de tests de la Trade Federation . Cette page explique comment utiliser Atest pour exécuter des tests Android.

Pour obtenir des informations générales sur l’écriture de tests pour Android, consultez Android Platform Testing .

Pour plus d'informations sur la structure globale d'Atest, reportez-vous au Guide du développeur Atest .

Pour plus d'informations sur l'exécution de tests dans des fichiers TEST_MAPPING via Atest, consultez Exécution de tests dans des fichiers TEST_MAPPING .

Pour ajouter une fonctionnalité à Atest, suivez le workflow du développeur Atest .

Configurez votre environnement

Pour configurer votre environnement Atest, suivez les instructions dans Configuration de l'environnement , Choix d'une cible et Construction du code .

Utilisation de base

Les commandes Atest prennent la forme suivante :

atest test-to-run [optional-arguments]

Arguments facultatifs

Le tableau suivant répertorie les arguments les plus couramment utilisés. Une liste complète est disponible via atest --help .

Option	Option longue	Description
-b	--build	Construit des cibles de test. (défaut)
-i	--install	Installe les artefacts de test (APK) sur l'appareil. (défaut)
-t	--test	Exécute les tests. (défaut)
-s	--serial	Exécute les tests sur le périphérique spécifié. Un appareil peut être testé à la fois.
-d	--disable-teardown	Désactive le démontage et le nettoyage des tests.
	--info	Affiche les informations pertinentes sur les cibles spécifiées, puis quitte.
	--dry-run	Effectuez des tests à sec sans réellement créer, installer ou exécuter des tests.
-m	--rebuild-module-info	Force une reconstruction du fichier module-info.json .
-w	--wait-for-debugger	Attend la fin du débogueur avant de s'exécuter.
-v	--verbose	Affiche la journalisation du niveau DEBUG.
	--iterations	Exécute les tests en boucle jusqu'à ce que l'itération maximale soit atteinte. (10 par défaut)
	--rerun-until-failure [COUNT=10]	Réexécute tous les tests jusqu'à ce qu'un échec se produise ou que l'itération maximale soit atteinte. (10 par défaut)
	--retry-any-failure [COUNT=10]	Réexécute les tests ayant échoué jusqu'à ce qu'ils soient réussis ou que l'itération maximale soit atteinte. (10 par défaut)
	--start-avd	Crée automatiquement un AVD et exécute des tests sur le périphérique virtuel.
	--acloud-create	Crée un AVD à l'aide de la commande acloud .
	--[CUSTOM_ARGS]	Spécifie des arguments personnalisés pour les exécuteurs de tests.
-a	--all-abi	Exécute les tests pour toutes les architectures de périphériques disponibles.
	--host	Exécute le test entièrement sur l'hôte sans périphérique. Remarque : L'exécution d'un test d'hôte nécessitant un périphérique avec --host échouera.
	--history	Affiche les résultats des tests par ordre chronologique.
	--latest-result	Imprime le dernier résultat du test.

Pour plus d’informations sur -b , -i et -t , consultez la section Spécifier les étapes : créer, installer ou exécuter .

Spécifier les tests

Pour exécuter des tests, spécifiez un ou plusieurs tests à l'aide de l'un des identifiants suivants :

• Nom du module
• Module : Classe
• Nom du cours
• Test d'intégration Tradefed
• Chemin du fichier
• Nom du paquet

Séparez les références à plusieurs tests avec des espaces, comme ceci :

atest test-identifier-1 test-identifier-2

Nom du module

Pour exécuter un module de test entier, utilisez son nom de module. Saisissez le nom tel qu'il apparaît dans les variables LOCAL_MODULE ou LOCAL_PACKAGE_NAME du fichier Android.mk ou Android.bp de ce test.

Exemples:

atest FrameworksServicesTests
atest CtsVideoTestCases

Remarque : Pour exécuter des tests non-modules intégrés à TradeFed (TF), utilisez plutôt TF Integration Test comme identifiant.

Module : Classe

Pour exécuter une seule classe dans un module, utilisez Module:Class . Le module est le même que celui décrit dans Nom du module . Class est le nom de la classe de test dans le fichier .java et peut être le nom complet de la classe ou le nom de base.

Exemples:

atest CtsVideoTestCases:VideoEncoderDecoderTest
atest FrameworksServicesTests:ScreenDecorWindowTests
atest FrameworksServicesTests:com.android.server.wm.ScreenDecorWindowTests

Remarque : Pour réduire le temps nécessaire à Atest pour localiser le test correct, nous vous recommandons d'utiliser le chemin de classe complet, comme indiqué dans le dernier exemple.

Nom du cours

Pour exécuter une seule classe sans indiquer explicitement un nom de module, utilisez le nom de la classe.

Exemples:

atest ScreenDecorWindowTests
atest VideoEncoderDecoderTest

Remarque : Pour réduire le temps nécessaire à Atest pour localiser le test correct, nous vous recommandons d'utiliser Module:Class au lieu du seul nom de la classe, dans la mesure du possible.

Test d'intégration Tradefed

Pour exécuter des tests intégrés directement dans TradeFed (non-modules), saisissez le nom tel qu'il apparaît dans la sortie de la commande tradefed.sh list configs . Par exemple:

Pour exécuter le test reboot.xml :

atest example/reboot

Pour exécuter le test native-benchmark.xml :

atest native-benchmark

Chemin du fichier

Atest prend en charge l'exécution de tests basés sur des modules et de tests basés sur l'intégration en saisissant le chemin d'accès à leur fichier ou répertoire de test, le cas échéant. Il prend également en charge l'exécution d'une seule classe en spécifiant le chemin d'accès au fichier Java de la classe. Les chemins relatifs et absolus sont pris en charge.

Exécuter un module

Les exemples suivants montrent deux façons d'exécuter le module CtsVideoTestCases à l'aide d'un chemin de fichier.

Exécuter à partir repo-root Android :

atest cts/tests/video

Exécuté à partir repo-root/cts/tests/video :

    atest .

Exécuter une classe de test

L'exemple suivant montre comment exécuter une classe spécifique dans le module CtsVideoTestCases à l'aide d'un chemin de fichier.

Depuis repo-root Android :

    atest cts/tests/video/src/android/video/cts/VideoEncoderDecoderTest.java

Exécuter un test d'intégration

L'exemple suivant montre comment exécuter un test d'intégration à l'aide d'un chemin de fichier à partir de repo-root Android :

    atest tools/tradefederation/contrib/res/config/example/reboot.xml

Nom du paquet

Atest prend en charge la recherche de tests par nom de package.

Exemples:

    atest com.android.server.wm
    atest com.android.uibench.janktests

Spécifier les étapes : créer, installer ou exécuter

Utilisez les options -b , -i et -t pour spécifier les étapes à exécuter. Si vous ne spécifiez aucune option, toutes les étapes sont exécutées.

Remarque : -b et -t peuvent s'exécuter individuellement, mais -i ne peut pas être exécuté sans -t .

• Construire des cibles uniquement : atest -b test-to-run
• Exécuter des tests uniquement : atest -t test-to-run
• Installez l'apk et exécutez les tests : atest -it test-to-run
• Construisez et exécutez, mais n'installez pas : atest -bt test-to-run

Atest peut forcer un test à ignorer l'étape de nettoyage ou de démontage. De nombreux tests, tels que CTS, nettoient le périphérique après l'exécution du test, donc essayer de réexécuter votre test avec -t échouera sans le paramètre --disable-teardown . Utilisez -d avant -t pour ignorer l'étape de nettoyage du test et tester de manière itérative.

atest -d test-to-run
atest -t test-to-run

Remarque : étant donné que -t désactive à la fois la configuration/l'installation et le démontage/nettoyage du périphérique, vous pouvez réexécuter votre test avec atest -t test-to-run autant de fois que vous le souhaitez.

Exécuter des méthodes spécifiques

Atest prend en charge l'exécution de méthodes spécifiques au sein d'une classe de test. Bien que l'ensemble du module doive être construit, cela réduit le temps nécessaire à l'exécution des tests. Pour exécuter des méthodes spécifiques, identifiez la classe en utilisant l'une des méthodes prises en charge pour identifier une classe (Module : Classe, chemin d'accès au fichier, etc.) et ajoutez le nom de la méthode :

atest reference-to-class#method1

Lorsque vous spécifiez plusieurs méthodes, séparez-les par des virgules :

atest reference-to-class#method1,method2,method3

Exemples:

atest com.android.server.wm.ScreenDecorWindowTests#testMultipleDecors
atest FrameworksServicesTests:ScreenDecorWindowTests#testFlagChange,testRemoval

Les deux exemples suivants montrent les méthodes préférées pour exécuter une seule méthode, testFlagChange . Ces exemples sont préférables à l'utilisation uniquement du nom de classe, car la spécification du module ou de l'emplacement du fichier Java permet à Atest de trouver le test beaucoup plus rapidement.

Utilisation du module : Classe :

atest FrameworksServicesTests:ScreenDecorWindowTests#testFlagChange

Depuis repo-root Android :

atest frameworks/base/services/tests/wmtests/src/com/android/server/wm/ScreenDecorWindowTests.java#testFlagChange

Plusieurs méthodes peuvent être exécutées à partir de différentes classes et modules :

atest FrameworksServicesTests:ScreenDecorWindowTests#testFlagChange,testRemoval ScreenDecorWindowTests#testMultipleDecors

Exécuter plusieurs cours

Pour exécuter plusieurs classes, séparez-les par des espaces de la même manière que pour exécuter plusieurs tests. Atest crée et exécute des classes de manière efficace, donc la spécification d'un sous-ensemble de classes dans un module améliore les performances par rapport à l'exécution de l'ensemble du module.

Pour exécuter deux classes dans le même module :

atest FrameworksServicesTests:ScreenDecorWindowTests FrameworksServicesTests:DimmerTests

Pour exécuter deux classes dans des modules différents :

atest FrameworksServicesTests:ScreenDecorWindowTests CtsVideoTestCases:VideoEncoderDecoderTest

Exécuter les binaires GTest

Atest peut exécuter les binaires GTest. Utilisez -a pour exécuter ces tests pour toutes les architectures de périphériques disponibles, qui dans cet exemple sont armeabi-v7a (ARM 32 bits) et arm64-v8a (ARM 64 bits).

Exemple de test de saisie :

atest -a libinput_tests inputflinger_tests

Remarque : Si vous devez uniquement exécuter des tests pour une architecture de périphérique spécifique, utilisez atest -- --abi arm64-v8a ou atest -- --abi armeabi-v7a

Pour sélectionner un binaire GTest spécifique à exécuter, utilisez deux points (:) pour spécifier le nom du test et un hashtag (#) pour spécifier davantage une méthode individuelle.

Par exemple, pour la définition de test suivante :

TEST_F(InputDispatcherTest, InjectInputEvent_ValidatesKeyEvents)

Exécutez ce qui suit pour spécifier l'intégralité du test :

atest inputflinger_tests:InputDispatcherTest

Ou exécutez un test individuel en utilisant ce qui suit :

atest inputflinger_tests:InputDispatcherTest#InjectInputEvent_ValidatesKeyEvents

Exécuter des tests dans TEST_MAPPING

Atest peut exécuter des tests dans les fichiers TEST_MAPPING .

Exécuter des tests de pré-soumission implicitement

Exécutez des tests de pré-soumission dans les fichiers TEST_MAPPING dans les répertoires actuel et parent :

atest

Exécutez des tests de pré-soumission dans les fichiers TEST_MAPPING dans /path/to/project et ses répertoires parents :

atest --test-mapping /path/to/project

Exécuter un groupe de test spécifié

Les groupes de tests disponibles sont : presubmit (par défaut), postsubmit , mainline-presubmit et all .

Exécutez des tests post-soumission dans les fichiers TEST_MAPPING dans les répertoires actuel et parent :

atest :postsubmit

Exécutez les tests de tous les groupes dans les fichiers TEST_MAPPING :

atest :all

Exécutez des tests post-soumission dans les fichiers TEST_MAPPING dans /path/to/project et ses répertoires parents :

atest --test-mapping /path/to/project:postsubmit

Exécutez les tests principaux dans les fichiers TEST_MAPPING dans /path/to/project et ses répertoires parents :

atest --test-mapping /path/to/project:mainline-presubmit

Exécuter des tests dans les sous-répertoires

Par défaut, Atest recherche uniquement les tests dans les fichiers TEST_MAPPING vers le haut (du répertoire actuel ou donné vers ses répertoires parents). Si vous souhaitez également exécuter des tests dans les fichiers TEST_MAPPING des sous-répertoires, utilisez --include-subdirs pour forcer Atest à inclure également ces tests :

atest --include-subdirs /path/to/project

Exécuter des tests en itération

Exécutez des tests en itération en passant l'argument --iterations . Qu'il réussisse ou échoue, Atest répétera le test jusqu'à ce que l'itération maximale soit atteinte.

Exemples:

Par défaut, Atest itère 10 fois. Le nombre d'itérations doit être un entier positif.

atest test-to-run --iterations
atest test-to-run --iterations 5

Les approches suivantes facilitent la détection des tests irréguliers :

Approche 1 : exécutez tous les tests jusqu'à ce qu'un échec se produise ou que l'itération maximale soit atteinte.

• Arrêtez-vous lorsqu'un échec se produit ou que l'itération atteint le 10ème tour (par défaut).

  atest test-to-run --rerun-until-failure
  

• Arrêtez-vous lorsqu'un échec se produit ou que l'itération atteint le 100ème tour.

  atest test-to-run --rerun-until-failure 100
  

Approche 2 : exécutez uniquement les tests ayant échoué jusqu'à ce qu'ils soient réussis ou que l'itération maximale soit atteinte.

• Supposons que test-to-run comporte plusieurs scénarios de test et que l’un des tests échoue. Exécutez uniquement le test ayant échoué 10 fois (par défaut) ou jusqu'à ce que le test réussisse.

  atest test-to-run --retry-any-failure
  

• Arrêtez d'exécuter le test échoué lorsqu'il réussit ou atteint le 100e tour.

  atest test-to-run --retry-any-failure 100
  

Exécuter des tests sur les AVD

Atest est capable d'exécuter des tests sur un AVD nouvellement créé. Exécutez acloud create pour créer un AVD et créer des artefacts, puis utilisez les exemples suivants pour exécuter vos tests.

Démarrez un AVD et exécutez des tests dessus :

acloud create --local-instance --local-image && atest test-to-run

Démarrez un AVD dans le cadre d'un test :

atest test-to-run --acloud-create "--local-instance --local-image"

Pour plus d'informations, exécutez acloud create --help .

Remarque : --acloud-create doit être le DERNIER argument facultatif. Tous les arguments qui le suivent sont traités comme des arguments de position pour l'AVD.

Remarque : --acloud-create et --start-avd ne suppriment pas les AVD nouvellement créés. Les utilisateurs doivent les supprimer manuellement.

Passer les options au module

Atest est capable de transmettre des options aux modules de test. Pour ajouter des options de ligne de commande TradeFed à votre exécution de test, utilisez la structure suivante et assurez-vous que vos arguments personnalisés suivent le format des options de ligne de commande Tradefed.

atest test-to-run -- [CUSTOM_ARGS]

Transmettez les options du module de test aux préparateurs cibles ou aux exécuteurs de tests définis dans le fichier de configuration de test :

atest test-to-run -- --module-arg module-name:option-name:option-value
atest GtsPermissionTestCases -- --module-arg GtsPermissionTestCases:ignore-business-logic-failure:true

Transmettez les options à un type ou une classe de coureur :

atest test-to-run -- --test-arg test-class:option-name:option-value
atest CtsVideoTestCases -- --test-arg com.android.tradefed.testtype.JarHosttest:collect-tests-only:true

Pour plus d'informations sur les options de test uniquement, consultez Passer les options aux modules .