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écuter la tâche 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 : |
Test unitaire d'instrumentation |
Exécuter la tâche 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 : |
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 :
- Compilez ou recompilez votre application principale et votre package de test.
- 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.
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 |
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
appelleonCreate(Bundle)
avec unBundle
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
etunit
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 testtestMethod1
.TestClass2
, qui contient les méthodes de testtestMethod2
ettestMethod3
.
- 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
.