Exécuter des tests depuis la ligne de commande

Ce document explique comment exécuter des tests directement depuis la ligne de commande. Dans ce document, nous partons du principe que vous savez déjà créer une application Android et écrire des tests pour celle-ci. Pour savoir comment créer des tests pour votre application, consultez Tester des applications sur Android.

Lorsque vous compilez votre application avec le système de compilation Gradle, le plug-in Android Gradle vous permet d'exécuter des tests à partir de votre projet Gradle à l'aide de la ligne de commande. Pour un contrôle plus précis, vous pouvez également choisir d'exécuter ces tests via une interface système Android Debug Bridge (adb). Cela peut être utile lors de l'exécution de tests dans un environnement d'intégration continue.

Pour découvrir comment exécuter des tests d'instrumentation automatiques à partir de la ligne de commande à l'aide d'appareils virtuels gérés par Gradle, consultez la section Adapter vos tests grâce aux appareils gérés par Gradle.

Exécuter des tests avec Gradle

Le plug-in Android Gradle vous permet d'exécuter des tests à partir de votre projet Gradle à l'aide de la ligne de commande.

Le tableau ci-dessous récapitule comment exécuter vos tests avec Gradle :

Tableau 1. Différentes manières d'exécuter des tests avec Gradle

Type de test unitaire Commande à exécuter Emplacement des résultats des tests
Test unitaire local Exécutez la tâche test : 

./gradlew test
Fichiers de résultats des tests HTML :
répertoire path_to_your_project/module_name/build/reports/tests/.

Fichiers de résultats des tests XML :
répertoire path_to_your_project/module_name/build/test-results/.

Test unitaire d'instrumentation Exécutez la tâche connectedAndroidTest : 

./gradlew connectedAndroidTest
Fichiers de résultats des tests HTML :
répertoire path_to_your_project/module_name/build/reports/androidTests/connected/.

Fichiers de résultats des tests XML :
répertoire path_to_your_project/module_name/build/outputs/androidTest-results/connected/.

Gradle prend en charge les abréviations de noms de tâches. Par exemple, vous pouvez lancer la tâche connectedAndroidTest en saisissant la commande suivante :

./gradlew cAT

Vous pouvez également choisir d'exécuter les tâches Gradle check et connectedCheck. Ces tâches exécutent respectivement vos tests locaux ou instrumentés, mais incluent d'autres vérifications ajoutées par d'autres plug-ins Gradle.

Exécuter des tests sur un module

Les tâches test et connectedAndroidTest exécutent des tests sur chaque module de votre projet. Pour exécuter des tests sur un module spécifique, ajoutez le nom du module et deux-points (:) comme préfixe à la tâche test ou connectedAndroidTest. Par exemple, la commande suivante n'exécute des tests d'instrumentation que pour le module mylibrary :

./gradlew mylibrary:connectedAndroidTest

Exécuter des tests sur une variante de compilation

Les tâches test et connectedAndroidTest exécutent des tests sur chaque variante de compilation de votre projet. Vous pouvez cibler une variante de compilation spécifique à l'aide de la syntaxe suivante :

  • Pour les tests unitaires locaux : 
    ./gradlew testVariantNameUnitTest
  • Pour les tests d'instrumentation :
    ./gradlew connectedVariantNameAndroidTest

Exécuter des méthodes ou des classes de test spécifiques

Lorsque vous exécutez des tests unitaires locaux, Gradle vous permet de cibler des tests spécifiques à l'aide de l'indicateur --tests. Par exemple, la commande suivante exécute uniquement les tests sampleTestMethod pour la variante de compilation spécifiée. Pour en savoir plus sur l'utilisation de l'indicateur --tests, consultez la documentation de Gradle relative au filtrage des tests.


./gradlew testVariantNameUnitTest --tests '*.sampleTestMethod'

Exécuter des tests avec adb

Lorsque vous exécutez des tests à partir de la ligne de commande avec Android Debug Bridge (adb), vous disposez de plus d'options pour sélectionner les tests à exécuter qu'avec toute autre méthode. Vous pouvez sélectionner des méthodes de test individuelles, filtrer les tests en fonction d'une annotation personnalisée ou spécifier des options de test. L'exécution des tests étant entièrement contrôlée depuis la ligne de commande, vous pouvez les personnaliser avec des scripts shell de différentes manières.

Pour exécuter un test à partir de la ligne de commande, exécutez adb shell afin de démarrer une interface système de ligne de commande sur votre appareil ou votre émulateur. Dans cette interface système, vous pouvez interagir avec le gestionnaire d'activités à l'aide de la commande am et de la sous-commande instrument pour exécuter vos tests.

En guise de raccourci, vous pouvez démarrer une interface système adb, appeler am instrument et spécifier des indicateurs de ligne de commande sur une ligne d'entrée. L'interface système s'ouvre sur l'appareil ou l'émulateur, exécute vos tests, génère un résultat, puis revient à la ligne de commande sur votre ordinateur.

Pour exécuter un test avec am instrument, procédez comme suit :

  1. Compilez ou recompilez votre application principale et votre package de test.
  2. Installez le package de test et les fichiers du package Android de l'application principale (fichiers APK) sur l'émulateur ou l'appareil Android actuel.

  3. Dans la ligne de commande, saisissez :

    adb shell am instrument -w <test_package_name>/<runner_class>

    Où <test_package_name> correspond au nom du package Android de votre application de test et <runner_class> au nom de la classe du lanceur de test Android que vous utilisez. Le nom du package Android correspond à la valeur de l'attribut de package de l'élément manifeste dans le fichier manifeste du package de test (AndroidManifest.xml).

    La classe du lanceur de test Android correspond généralement à AndroidJUnitRunner :

    adb shell am instrument -w com.android.example/androidx.test.runner.AndroidJUnitRunner

Les résultats du test s'affichent dans STDOUT.

Indicateurs d'instrumentation am

Pour obtenir la liste de tous les indicateurs à utiliser avec la commande am instrument, exécutez adb shell am help. Certains indicateurs importants sont décrits dans le tableau suivant :

Tableau 2. Indicateurs am instrument clés

Indicateur Valeur Description
-w (aucune) Oblige am instrument à attendre la fin de l'instrumentation avant de s'arrêter. L'interface système reste ainsi ouverte jusqu'à la fin des tests. Cet indicateur est requis pour voir les résultats de vos tests.
-r (aucune) Résultats au format brut. Utilisez cet indicateur lorsque vous souhaitez collecter des mesures de performances afin qu'elles ne soient pas mises en forme en tant que résultats de test. Cet indicateur est conçu pour être utilisé avec l'indicateur -e perf true (documenté dans la section Options d'instrumentation am).
-e <test_options> Fournit des options de test sous forme de paires clé/valeur. L'outil am instrument les transmet à la classe d'instrumentation spécifiée à l'aide de sa méthode onCreate(). Vous pouvez spécifier plusieurs occurrences de -e <test_options>. Les clés et les valeurs sont décrites dans la section Options d'instrumentation am. Vous pouvez uniquement utiliser ces paires clé/valeur avec AndroidJUnitRunner ou InstrumentationTestRunner et les sous-classes correspondantes. Leur utilisation avec une autre classe n'a aucun effet.
--no-hidden-api-checks (aucune) Désactive les restrictions liées à l'utilisation des API masquées. Pour en savoir plus sur les API masquées et leur impact potentiel sur votre application, consultez Restrictions concernant les interfaces non SDK.

Options d'instrumentation am

L'outil am instrument transmet les options de test à AndroidJUnitRunner ou InstrumentationTestRunner sous la forme de paires clé/valeur, à l'aide de l'indicateur -e, avec la syntaxe suivante :

-e <key> <value>

Certaines clés acceptent plusieurs valeurs. Vous pouvez spécifier différentes valeurs dans une liste d'éléments séparés par une virgule. Par exemple, cet appel de AndroidJUnitRunner fournit plusieurs valeurs pour la clé package :

adb shell am instrument -w -e package com.android.test.package1,com.android.test.package2 \
> com.android.test/androidx.test.runner.AndroidJUnitRunner

Le tableau suivant recense les paires clé/valeur que vous pouvez utiliser avec le lanceur de test :

Tableau 3. Paires clé/valeur avec indicateur -e à utiliser avec le lanceur de test

Clé Valeur Description
package <Java_package_name> Nom complet de package Java pour l'un des packages d'application de test. Tout scénario de test utilisant ce nom de package est exécuté. Notez qu'il ne s'agit pas d'un nom de package Android. Un package de test possède un seul nom de package Android, mais peut contenir plusieurs packages Java.
class <class_name> Nom complet de classe Java pour l'une des classes de scénario de test. Seul ce scénario de test est exécuté.
<class_name>#method name Nom complet de classe de scénario de test et une de ses méthodes. Seule cette méthode est exécutée. Notez le signe dièse (#) entre le nom de la classe et le nom de la méthode.
func true Exécute toutes les classes de test qui étendent InstrumentationTestCase.
unit true Exécute toutes les classes de test qui n'étendent pas InstrumentationTestCase ni PerformanceTestCase.
size [small | medium | large] Exécute une méthode de test annotée par taille. Les annotations sont @SmallTest, @MediumTest et @LargeTest.
perf true Exécute toutes les classes de test qui implémentent PerformanceTestCase. Lorsque vous utilisez cette option, spécifiez l'indicateur -r pour am instrument afin de conserver la sortie au format brut, sans la reformater en tant que résultat de test.
debug true Exécute des tests en mode débogage.
log true Charge et consigne tous les tests spécifiés, mais ne les exécute pas. Les informations relatives aux tests apparaissent dans STDOUT. Utilisez-les pour vérifier les combinaisons d'autres filtres et spécifications de test.
emma true Exécute une analyse de couverture de code EMMA et écrit la sortie dans /data/<app_package>/coverage.ec sur l'appareil. Pour remplacer l'emplacement du fichier, utilisez la clé coverageFile décrite dans l'entrée suivante.

Remarque : Cette option implique une compilation avec instrumentation EMMA de l'application de test, que vous pouvez générer avec la cible coverage.

coverageFile <filename> Remplace l'emplacement par défaut du fichier de couverture EMMA sur l'appareil. Spécifiez cette valeur en tant que chemin et nom de fichier au format UNIX. Le nom de fichier par défaut est décrit dans l'entrée de la clé emma.

Lorsque vous utilisez l'indicateur -e, gardez à l'esprit ce qui suit :

  • am instrument appelle onCreate(Bundle) avec un Bundle contenant les paires clé/valeur.
  • La clé package est prioritaire sur la clé class. Si vous spécifiez un package, puis que vous définissez séparément une classe dans ce package, Android exécute tous les tests du package et ignore la clé de classe.
  • Les clés func et unit s'excluent mutuellement.

Exemples d'utilisation

Les sections suivantes fournissent des exemples d'utilisation de am instrument pour exécuter des tests. Ils reposent sur la structure suivante :

  • Le package de test porte le nom du package Android com.android.demo.app.tests.
  • Deux classes de test d'instrumentation :
    • TestClass1, qui contient la méthode de test testMethod1.
    • TestClass2, qui contient les méthodes de test testMethod2 et testMethod3.
  • Le lanceur de test est AndroidJUnitRunner.

Exécuter l'intégralité du package de test

Pour exécuter toutes les classes de test du package de test, saisissez :

adb shell am instrument -w com.android.demo.app.tests/androidx.test.runner.AndroidJUnitRunner

Exécuter tous les tests d'une classe de scénario de test

Pour exécuter tous les tests de la classe TestClass1, saisissez :

adb shell am instrument -w  \
> -e class com.android.demo.app.tests.TestClass1 \
> com.android.demo.app.tests/androidx.test.runner.AndroidJUnitRunner

Sélectionner un sous-ensemble de tests

Pour exécuter tous les tests de la classe TestClass1 et la méthode testMethod3 dans TestClass2, saisissez :

adb shell am instrument -w \
> -e class com.android.demo.app.tests.TestClass1,com.android.demo.app.tests.TestClass2#testMethod3 \
> com.android.demo.app.tests/androidx.test.runner.AndroidJUnitRunner

Vous trouverez d'autres cas d'utilisation dans la documentation de référence de l'API AndroidJUnitRunner.