Exécuter des tests (Atest)

Atest est un outil de ligne de commande qui permet aux utilisateurs de compiler, d'installer et d'exécuter des tests Android en local. Il accélère considérablement les nouvelles exécutions de tests sans nécessiter de connaissances sur les options de ligne de commande du harnais de test Trade Federation . Cette page explique comment utiliser Atest pour exécuter des tests Android.

Pour obtenir des informations générales sur la création de tests pour Android, consultez la section Tests de 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 du développeur Atest.

Configurer votre environnement

Pour configurer votre environnement Atest, suivez les instructions des sections Configurer l' environnement, Choisir une cible et Compiler le code.

Utilisation de base

Les commandes Atest se présentent comme suit :

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 Compile les 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é. Un seul appareil peut être testé à la fois.
-d --disable-teardown Désactive la suppression et le nettoyage des tests.
--dry-run Exécute Atest sans compiler, 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 se termine avant l'exécution.
-v --verbose Affiche la journalisation au niveau DEBUG.
--iterations Exécute les tests en boucle jusqu'à ce que le nombre maximal d'itérations soit atteint. (10 par défaut)
--rerun-until-failure [COUNT=10] Réexécute tous les tests jusqu'à ce qu'un échec se produise ou que le nombre maximal d'itérations soit atteint. (10 par défaut)
--retry-any-failure [COUNT=10] Réexécute les tests ayant échoué 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 lanceurs de test.
-a --all-abi Exécute les tests pour toutes les architectures d'appareil disponibles.
--host Exécute le test entièrement sur l'hôte sans appareil.
Remarque : L'exécution d'un test d'hôte qui nécessite un appareil avec --host échouera.
--history Affiche les résultats des tests par ordre chronologique.
--latest-result Affiche le dernier résultat du test.

Pour en savoir plus sur -b, -i et -t, consultez la section Spécifier des étapes : compiler, installer ou exécuter.

Spécifier des tests

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

  • Nom du module
  • Module:Classe
  • Nom de la classe
  • Test d'intégration Tradefed
  • Chemin d'accès du 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 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

Module:Classe

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

Exemples :

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

Nom de la 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 Tradefed

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

Pour exécuter le reboot.xml test :

atest example/reboot

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

atest native-benchmark

Chemin d'accès du fichier

Atest permet d'exécuter 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, selon le cas. 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 d'accès relatifs et absolus sont acceptés.

Exécuter un module

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

Exécuter à partir de la racine du dépôt Android repo-root :

atest cts/tests/video

Exécuter à partir de la racine du dépôt Androidrepo-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 de fichier.

À partir de 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 de fichier à partir de la racine du dépôt 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 des étapes : compiler, installer ou exécuter

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.

  • Compiler uniquement les cibles : atest -b test-to-run
  • Exécuter uniquement les tests : atest -t test-to-run
  • Installer l'APK et exécuter les tests : atest -it test-to-run
  • Compiler et exécuter, mais ne pas installer : atest -bt test-to-run

Atest peut forcer un test à ignorer l'étape de nettoyage ou de suppression. De nombreux tests, tels que CTS, nettoient l'appareil après l'exécution du test. Par conséquent, si vous essayez de réexécuter votre test avec -t, l'opération é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

Exécuter des méthodes spécifiques

Atest permet d'exécuter des méthodes spécifiques dans une classe de test. Bien que l'ensemble du module doive être compilé, cela réduit le temps nécessaire à l'exécution des tests. Pour exécuter des méthodes spécifiques, identifiez la classe à l'aide de l'une des méthodes compatibles pour identifier une classe (Module:Classe, chemin d'accès de fichier, etc.), puis 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 du nom de la classe uniquement, car la spécification du module ou de l'emplacement du fichier Java permet à Atest de trouver le test beaucoup plus rapidement.

Utiliser Module:Classe :

atest FrameworksServicesTests:ScreenDecorWindowTests#testFlagChange

À partir d'Android repo-root :

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 classes

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 les classes de manière efficace. Par conséquent, 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 des binaires GTest

Atest peut exécuter des binaires GTest. Utilisez -a pour exécuter ces tests pour toutes les architectures d'appareil disponibles, qui dans cet exemple sont 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 signe deux-points (:) pour spécifier le nom du test et un dièse (#) pour spécifier 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'ensemble du test : 

atest inputflinger_tests:InputDispatcherTest

Ou exécutez 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 des fichiers TEST_MAPPING.

Exécuter des tests de pré-envoi de manière implicite

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

atest

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

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

Exécuter un groupe de tests spécifié

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

Exécuter des tests de post-envoi dans des fichiers TEST_MAPPING dans les répertoires actuel et parent :

atest :postsubmit

Exécuter des tests de tous les groupes dans des fichiers TEST_MAPPING :

atest :all

Exécuter des tests de post-envoi dans des fichiers TEST_MAPPING dans /path/to/project et ses répertoires parents :

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

Exécuter des tests de la branche principale dans des 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 des sous-répertoires

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

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

Exécuter des tests de manière itérative

Exécutez des tests de manière itérative en transmettant l'argument --iterations. Qu'il réussisse ou échoue, Atest répète le test jusqu'à ce que le nombre maximal d'itérations soit atteint.

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

Approche 1 : Exécutez 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 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 100e tour. 
    atest test-to-run --rerun-until-failure 100

Approche 2 : N'exécutez que les tests ayant échoué 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 des tests échoue. N'exécutez que 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 compiler des artefacts, puis utilisez les exemples suivants pour exécuter vos tests.

Démarrer un AVD et exécuter des tests dessus :

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

Démarrer un AVD dans le cadre d'une 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 des options de ligne de commande Tradefed.

atest test-to-run -- [CUSTOM_ARGS]

Transmettre des options de module de test aux préparateurs de cibles ou aux lanceurs de test 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

Transmettre des options à un type ou une classe de lanceur :

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.