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, ce qui accélère considérablement les nouvelles exécutions de tests sans nécessiter de connaître les options de ligne de commande du bouquet de tests de la Trade Federation. Cette page explique comment utiliser Atest pour exécuter des tests Android.

Pour en savoir plus sur l'écriture de tests pour Android, consultez Tester la plate-forme Android.

Pour en savoir plus sur la structure globale d'Atest, consultez le guide du développeur Atest.

Pour en savoir plus sur l'exécution de tests dans des fichiers TEST_MAPPING via Atest, consultez la section Exécuter des tests dans des fichiers TEST_MAPPING.

Pour ajouter une fonctionnalité à Atest, suivez le workflow de développement Atest.

Configurer votre environnement

Pour configurer votre environnement Atest, suivez les instructions de la section Configurer l'environnement, Choisir une cible et Créer le code.

Utilisation de base

Les commandes Atest se présentent sous 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	Crée des cibles de test. (par défaut)
-i	--install	Installe les artefacts de test (APK) sur l'appareil. (par défaut)
-t	--test	Exécute les tests. (par défaut)
-s	--serial	Exécute les tests sur l'appareil spécifié. Vous ne pouvez tester qu'un seul appareil à la fois.
-d	--disable-teardown	Désactive le démontage et le nettoyage des tests.
	--dry-run	Les simulations Atest permettent de tester sans créer, installer ni exécuter de tests.
-m	--rebuild-module-info	Force la recompilation du fichier module-info.json.
-w	--wait-for-debugger	Attend que le débogueur ait terminé avant de s'exécuter.
-v	--verbose	Affiche la journalisation de niveau DEBUG.
	--iterations	Exécute les tests en boucle jusqu'à atteindre l'itération maximale. (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 échoués jusqu'à ce qu'ils réussissent ou que le nombre maximal d'itérations soit atteint. (10 par défaut)
	--start-avd	Crée automatiquement un AVD et exécute des tests sur l'appareil virtuel.
	--acloud-create	Crée un AVD à l'aide de la commande acloud.
	--[CUSTOM_ARGS]	Spécifie des arguments personnalisés pour les outils de test.
-a	--all-abi	Exécute les tests pour toutes les architectures d'appareils disponibles.
	--host	Exécute le test complètement sur l'hôte, sans appareil. Remarque: L'exécution d'un test d'hôte nécessitant un appareil avec --host échouera.
	--history	Affiche les résultats des tests dans l'ordre chronologique.
	--latest-result	Imprime le dernier résultat du test.

Pour en savoir plus sur -b, -i et -t, consultez la section Spécifier les étapes: compilation, installation ou exécution.

Spécifier des 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 de classe.
• Test d'intégration de Tradefed
• Chemin d'accès au fichier
• Nom du package

Séparez les références à plusieurs tests par des espaces, comme suit:

atest test-identifier-1 test-identifier-2

Nom du module

Pour exécuter un module de test complet, utilisez son nom. 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

Module:Classe

Pour exécuter une classe unique dans un module, utilisez Module:Class. Module est identique à celui décrit dans Nom du module. Class est le nom de la classe de test dans le fichier .java. Il peut s'agir du nom de classe complet ou du nom de base.

Exemples :

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

Nom de classe.

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

Exemples :

atest ScreenDecorWindowTests
atest VideoEncoderDecoderTest

Test d'intégration de Tradefed

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

Pour exécuter le test reboot.xml:

atest example/reboot

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

atest native-benchmark

Chemin d'accès au fichier

Atest permet d'exécuter à la fois des tests basés sur des modules et des 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 permet également d'exécuter une seule classe en spécifiant le chemin d'accès au fichier Java de la classe. Les chemins relatifs et absolus sont acceptés.

Exécuter un module

Les exemples suivants montrent deux manières d'exécuter le module CtsVideoTestCases à l'aide d'un chemin d'accès à un fichier.

Exécuter depuis Android repo-root:

atest cts/tests/video

Exécuter depuis Android 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 d'accès au fichier.

Depuis Android repo-root:

    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 d'accès à partir d'Android repo-root:

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

Nom du package

Atest permet de rechercher des tests par nom de package.

Exemples :

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

Spécifier les étapes: compilation, installation ou exécution

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

• Cibles de compilation uniquement: atest -b test-to-run
• Exécuter des tests uniquement: atest -t test-to-run
• Installer l'APK et exécuter des tests: atest -it test-to-run
• Compilez et exécutez, mais ne l'installez pas: atest -bt test-to-run

Un test peut forcer un test à ignorer l'étape de nettoyage ou de démontage. De nombreux tests, tels que CTS, nettoient l'appareil après l'exécution du test. Par conséquent, toute tentative de réexécution de votre test avec -t échouera sans le paramètre --disable-teardown. Utilisez -d avant -t pour ignorer l'étape de nettoyage du test et effectuer un test itératif.

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

Exécuter des méthodes spécifiques

Atest permet d'exécuter des méthodes spécifiques dans une classe de test. Bien que le module entier doive être compilé, cela réduit le temps nécessaire pour exécuter les tests. Pour exécuter des méthodes spécifiques, identifiez la classe à l'aide de l'une des méthodes compatibles (Module:Class, chemin d'accès au fichier, etc.) et ajoutez le nom de la méthode:

atest reference-to-class#method1

Si vous spécifiez plusieurs méthodes, séparez-les par une virgule:

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 recommandées pour exécuter une seule méthode, testFlagChange. Il est préférable d'utiliser ces exemples plutôt que de n'utiliser que le nom de la classe, car spécifier le module ou l'emplacement du fichier Java permet à Atest de trouver le test beaucoup plus rapidement.

Utilisation de Module:Class:

atest FrameworksServicesTests:ScreenDecorWindowTests#testFlagChange

Depuis Android repo-root:

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

Vous pouvez exécuter plusieurs méthodes à 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 compile et exécute des classes de manière efficace. Par conséquent, spécifier 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 différents modules:

atest FrameworksServicesTests:ScreenDecorWindowTests CtsVideoTestCases:VideoEncoderDecoderTest

Exécuter des binaires GTest

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

Exemple de test d'entrée:

atest -a libinput_tests inputflinger_tests

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

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

TEST_F(InputDispatcherTest, InjectInputEvent_ValidatesKeyEvents)

Exécutez la commande suivante pour spécifier l'intégralité du test :

atest inputflinger_tests:InputDispatcherTest

Vous pouvez également exécuter un test individuel à l'aide de la commande suivante :

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 les tests présoumission de manière implicite

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

atest

Exécutez des tests avant l'envoi 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 test disponibles sont les suivants: presubmit(par défaut), postsubmit, mainline-presubmit et all.

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

atest :postsubmit

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

atest :all

Exécutez les 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 de /path/to/project et ses répertoires parents:

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

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

Par défaut, Atest ne recherche les tests que dans les fichiers TEST_MAPPING supérieurs (du répertoire actuel ou du répertoire 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 ces tests également:

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

Exécuter des tests en itération

Exécutez des tests en itération en transmettant l'argument --iterations. Que le test réussisse ou échoue, Atest le répète jusqu'à atteindre l'itération maximale.

Exemples :

Par défaut, Atest effectue 10 itérations. 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:

Méthode 1: exécuter tous les tests jusqu'à ce qu'un échec se produise ou que le nombre maximal d'itérations soit atteint

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

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

• Arrêtez-vous lorsqu'une erreur se produit ou que l'itération atteint le 100e tour.

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

Approche 2: Exécutez uniquement les tests échoués jusqu'à ce qu'ils réussissent ou que le nombre maximal d'itérations soit atteint.

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

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

• Arrêtez l'exécution du test ayant échoué lorsqu'il réussit ou atteint le 100e tour.

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

Exécuter des tests sur des AVD

Atest peut exécuter des tests sur un AVD nouvellement créé. Exécutez acloud create pour créer un AVD et créer des artefacts de compilation, 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 exécution de test:

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

Pour en savoir plus, exécutez acloud create --help.

Transmettre des options au module

Atest peut 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 respectent le format d'option de ligne de commande Tradefed.

atest test-to-run -- [CUSTOM_ARGS]

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

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

Transmettre des 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 en savoir plus sur les options réservées aux tests, consultez la section Transmettre des options aux modules.