Commencer les tests avec la gcloud CLI

Ce guide explique comment exécuter un test d'instrumentation, Robo ou Game Loop à l'aide de la gcloud CLI.

Pour obtenir la liste complète des gcloud commandes que vous pouvez utiliser avec votre application Android dans Test Lab, consultez la documentation de référence pour gcloud firebase test android.

Avant de commencer

Si ce n'est pas déjà fait, ajoutez Firebase à votre projet Android.

Étape 1 : Configurer gcloud CLI

1. Téléchargez le SDK Google Cloud.

Cela inclut l'outil gcloud CLI.

2. Assurez-vous que votre installation est à jour :

   gcloud components update
   

3. Connectez-vous à la gcloud CLI à l'aide de votre compte Google :

   gcloud auth login
   

4. Définissez votre projet Firebase dans gcloud, où PROJECT_ID correspond à l'ID de votre projet Firebase :

   gcloud config set project PROJECT_ID
   

Étape 2 : Vérifier les appareils de test disponibles

Utilisez les commandes gcloud suivantes pour afficher les appareils de test et les paramètres régionaux disponibles pour votre test.

Vous pouvez également télécharger l'exemple d'application Bloc-notes pour commencer à exécuter les commandes immédiatement. Utilisez le fichier binaire app-debug-unaligned.apk et le fichier de tests d'instrumentation app-debug-test-unaligned.apk, qui se trouvent dans NotePad/app/build/outputs/apk/.

• models list: obtenez la liste actuelle des appareils Android sur lesquels vous pouvez effectuer des tests.

  gcloud firebase test android models list

  Dans le résultat de la commande :

  • La colonne MODEL_ID contient l'identifiant que vous pourrez utiliser ultérieurement pour exécuter des tests sur le modèle d'appareil.
  • La colonne OS_VERSION_ID contient les versions du système d'exploitation compatibles avec l'appareil.

  Exemple de résultat :

  

• models describe : obtenez plus d'informations sur un MODEL_ID Android spécifique.

  gcloud firebase test android models describe MODEL_ID

  Le résultat contient la marque, le fabricant, les versions du système d'exploitation, les niveaux d'API compatibles, les interfaces binaires d'application (ABI) compatibles, les dates de sortie et indique si l'appareil est physique ou virtuel.

• versions list: obtenez la liste des versions du système d'exploitation actuellement disponibles pour les tests.

  gcloud firebase test android versions list

  Vous pouvez utiliser un identifiant de l'une des deux premières colonnes du résultat de la commande (OS_VERSION_ID et VERSION) pour exécuter ultérieurement des tests sur une version du système d'exploitation Android. Si vous ne spécifiez pas les versions du système d'exploitation Android à tester, la valeur par défaut indiquée dans la colonne TAGS est utilisée.

  Exemple de résultat :

  

• locales list : obtenez la liste actuelle des paramètres régionaux disponibles pour les tests.

  gcloud firebase test android locales list

  La première colonne du résultat de la commande, LOCALE, contient l'identifiant que vous pourrez utiliser ultérieurement pour exécuter des tests sur un paramètre régional. Si vous ne spécifiez pas les paramètres régionaux à tester, l'anglais est utilisé par défaut.

Étape 3 : Exécuter votre test

Maintenant que vous connaissez la gamme de modèles d'appareils, de paramètres régionaux et de versions du système d'exploitation disponibles pour tester votre application, vous pouvez spécifier des appareils à l'aide de la commande gcloud firebase test android run et de l'option --device pour exécuter des tests Robo ou d'instrumentation.

Remarque : L'option --device est désormais la méthode recommandée pour spécifier les appareils de test. Elle ne peut pas être utilisée conjointement avec --devices-ids, --os-version-ids, --locales ni --orientations. Pour en savoir plus sur ces options héritées, consultez la liste des options de dimension d'appareil obsolètes dans gcloud firebase test android run.

Exécuter un test Robo

Même si vous n'avez pas de tests d'instrumentation, vous pouvez toujours rechercher des bugs dans votre application. Utilisez le test Robo pour effectuer une analyse automatisée de l'interface utilisateur de votre application. Le test Robo teste l'application en effectuant une analyse statique des différents chemins d'accès à l'interface utilisateur de l'application, puis en explorant l'application pour détecter les plantages et autres problèmes potentiels.

Pour exécuter un test Robo, exécutez l'exemple de commande suivant :

gcloud firebase test android run \
  --type robo \
  --app app-debug-unaligned.apk \
  --device model=Nexus6,version=21,locale=en,orientation=portrait  \
  --device model=Nexus7,version=19,locale=fr,orientation=landscape \
  --timeout 90s \
  --client-details matrixLabel="Example matrix label"

• Le paramètre --type robo est implicite si aucune valeur --type n'est spécifiée.
• Pour vous aider à identifier et à localiser vos matrices de test dans la console Firebase, vous pouvez utiliser l'option facultative --client-details matrixLabel="Example matrix label" pour étiqueter votre matrice de test.
• Pour afficher l'ensemble complet des options de ligne de commande permettant d'exécuter des tests, saisissez gcloud help firebase test android run.

Au lieu de spécifier ces arguments sur la ligne de commande, vous pouvez également les spécifier dans un fichier d'arguments au format YAML. Exécutez gcloud topic arg-files pour découvrir comment utiliser cette fonctionnalité.

Pour savoir comment examiner les résultats du test Robo, consultez Analyser les résultats de vos tests.

Exécuter un test d'instrumentation

Utilisez maintenant l'outil de ligne de commande gcloud pour exécuter les tests Espresso de l'application Bloc-notes sur les configurations d'appareils Android spécifiées. Utilisez le type de test instrumentation pour exécuter les tests dans app-debug-test-unaligned.apk comme suit :

gcloud firebase test android run \
  --type instrumentation \
  --app app-debug-unaligned.apk \
  --test app-debug-test-unaligned.apk \
  --device model=Nexus6,version=21,locale=en,orientation=portrait  \
  --device model=Nexus7,version=19,locale=fr,orientation=landscape
  --client-details matrixLabel="Example matrix label"

• Le paramètre d'instrumentation --type est implicite si un APK de test est spécifié avec --test.
• Pour vous aider à identifier et à localiser vos matrices de test dans la console Firebase, vous pouvez utiliser l'option facultative --client-details matrixLabel="Example matrix label" pour étiqueter votre matrice de test.
• Pour afficher l'ensemble complet des options de ligne de commande permettant d'exécuter des tests, saisissez gcloud help firebase test android run.

Au lieu de spécifier ces arguments sur la ligne de commande, vous pouvez également les spécifier dans un fichier d'arguments au format YAML. Exécutez gcloud topic arg-files pour découvrir comment utiliser cette fonctionnalité.

La gcloud CLI est compatible avec Android Test Orchestrator. Orchestrator nécessite AndroidJUnitRunner v1.1 ou une version ultérieure. Pour l'activer, utilisez gcloud firebase test android run avec l'
--use-orchestrator option. Pour le désactiver, utilisez l'option --no-use-orchestrator.

Attention : Pour éviter de dépenser votre quota ou d'être facturé pour des tests défectueux, exécutez Orchestrator en local avant de l'essayer dans Test Lab. Vérifiez qu'Orchestrator fonctionne dans votre application en exécutant un test sur votre propre machine avant d'importer votre APK. N'oubliez pas que les tests avec Orchestrator prennent un peu plus de temps qu'avec d'autres outils. Ils peuvent avoir un impact sur votre facturation ou entraîner le dépassement de votre délai d'inactivité.

Vous pouvez également contrôler la façon dont Test Lab exécute vos tests d'instrumentation à l'aide d'options supplémentaires qui ne sont pas affichées ci-dessus. Par exemple, vous pouvez utiliser l'option --test-targets pour tester une seule classe ou une méthode de classe utilisée par votre APK de test. Vous pouvez également déterminer si votre test ayant échoué était réellement instable ou non à l'aide de l'option --num-flaky-test-attempts, qui spécifie le nombre de tentatives d'exécution d'un test si un ou plusieurs de ses scénarios de test échouent pour une raison quelconque. Pour en savoir plus, consultez gcloud firebase test android run.

Rapports de couverture du code pour les tests d'instrumentation

Test Lab est compatible avec les outils de création de rapports de couverture du code EMMA et JaCoCo. Si l'un de ces outils est intégré à la compilation de votre application, vous pouvez obtenir un rapport de couverture du code pour Test Lab tests en exécutant gcloud firebase test android run avec des arguments supplémentaires. Si Android Test Orchestrator n'est pas activé, utilisez les éléments suivants :

gcloud firebase test android run \
  --type instrumentation \
  --app your-app.apk \
  --test your-app-test.apk \
  --device model=TestDevice,version=AndroidVersion  \
  --environment-variables coverage=true,coverageFile="/sdcard/Download/coverage.ec" \
  --directories-to-pull /sdcard/Download

Si vous générez des rapports de couverture du code tout en utilisant Android Test Orchestrator, modifiez vos variables d'environnement comme suit :

gcloud firebase test android run \
  --type instrumentation \
  --app your-app.apk \
  --test your-app-test.apk \
  --device model=TestDevice,version=AndroidVersion  \
  --environment-variables clearPackageData=true,coverage=true,coverageFilePath="/sdcard/Download/" \
  --directories-to-pull /sdcard/Download

Une fois que Test Lab a terminé l'exécution de vos tests, recherchez vos rapports de couverture du code dans Google Cloud Storage :

1. Ouvrez le lien de la console Firebase que l'outil gcloud a imprimé au-dessus du tableau des résultats de test dans votre terminal.
2. Cliquez sur une exécution de test dans la liste de ce lien pour ouvrir la page de détails de cette exécution.
3. Cliquez sur Résultats des tests pour accéder au Cloud Storage bucket contenant les résultats des tests de cette exécution.
4. Ouvrez artifacts/coverage.ec pour afficher votre rapport de couverture du code.

Remarque : L'extraction du répertoire sdcard/Download pour chaque test place tous les fichiers de ce répertoire dans le bucket Cloud Storage du test. Si vous disposez d'un forfait Blaze et que votre application crée de nombreux fichiers dans ce répertoire, l'extraction du répertoire peut entraîner des frais de stockage supplémentaires.

Analyser les résultats de vos tests

Après quelques minutes, un résumé de base des résultats de vos tests est imprimé par l'outil gcloud :

Le résultat de l'exécution de votre test de ligne de commande inclut également un lien permettant d'afficher les résultats des tests. Pour en savoir plus sur l'interprétation de ces résultats, consultez Analyser les résultats Firebase Test Lab pour Android.

Connexion et saisie de texte personnalisées avec le test Robo

Le test Robo remplit automatiquement les écrans de connexion qui utilisent un compte Google pour l'authentification, sauf si vous utilisez le --no-auto-google-login paramètre. Il peut également remplir des écrans de connexion personnalisés à l'aide des identifiants de compte de test que vous fournissez. Vous pouvez également utiliser ce paramètre pour fournir un texte d'entrée personnalisé pour d'autres champs de texte utilisés par votre application.

Pour remplir les champs de texte de votre application, utilisez le --robo-directives paramètre et fournissez une liste de paires key-value séparées par des virgules, où la key correspond au nom de la ressource Android de l'élément d'interface utilisateur cible et la value est la chaîne de texte. Vous pouvez également utiliser cette option pour indiquer à Robo d'ignorer des éléments d'interface utilisateur spécifiques (par exemple, le bouton "Se déconnecter"). EditText champs sont compatibles, mais pas les champs de texte des éléments d'interface utilisateur WebView.

Par exemple, vous pouvez utiliser le paramètre suivant pour une connexion personnalisée :

--robo-directives username_resource=username,password_resource=password

Attention : N'utilisez que des identifiants pour les comptes de test qui ne sont pas associés à des utilisateurs réels.

Commandes et options disponibles

La gcloud CLI de Test Lab propose plusieurs commandes et options qui vous permettent d 'exécuter des tests avec différentes spécifications :

• Option Android Test Orchestrator : option permettant d'activer Orchestrator, un outil qui vous permet d'exécuter chacun des tests de votre application dans sa propre invocation de Instrumentation. Test Lab exécute toujours la dernière version d'Orchestrator.

• Options de test Game Loop: ensemble d'options de configuration qui activent et contrôlent un "mode démo" pour simuler les actions des joueurs dans les applications de jeu. En savoir plus sur l'exécution de tests Game Loop avec Test Lab

• Option de partitionnement uniforme (en version bêta): Option qui spécifie le nombre de partitions dans lesquelles vous souhaitez répartir uniformément les scénarios de test. Les partitions sont exécutées en parallèle sur des appareils distincts.

  Remarque : Les limites pour les appareils physiques sont de 50, 200 pour les appareils virtuels Arm et 500 pour les appareils virtuels x86. Cela s'applique également à l'option de partitionnement manuel.

• Option de partitionnement manuel (en version bêta) : Option qui spécifie un groupe de packages, de classes et/ou de scénarios de test à exécuter dans une partition (un groupe de scénarios de test). Les partitions sont exécutées en parallèle sur des appareils distincts.

• Option de profils de trafic réseau (en version bêta): Option qui spécifie le profil réseau utilisé par vos tests avec des appareils physiques. Les profils réseau émulent diverses conditions de réseau, ce qui vous permet de tester les performances de votre application sur des réseaux peu fiables ou imprévisibles.

Créer des scripts pour les commandes gcloud avec Test Lab

Vous pouvez utiliser des scripts shell ou des fichiers de commandes pour automatiser les commandes de test d'applications mobiles que vous exécuteriez normalement à l'aide de la ligne de commande gcloud. L'exemple de script bash suivant exécute un test d'instrumentation avec un délai d'inactivité de deux minutes et indique si l'exécution du test s'est terminée correctement :

if gcloud firebase test android run --app my-app.apk --test my-test.apk --timeout 2m
then
    echo "Test matrix successfully finished"
else
    echo "Test matrix exited abnormally with non-zero exit code: " $?
fi

Codes de sortie du script

Test Lab fournit plusieurs codes de sortie que vous pouvez utiliser pour mieux comprendre les résultats des tests que vous exécutez à l'aide de scripts ou de fichiers de commandes.

Codes de sortie de script pour Test Lab

Code de sortie	Remarques
0	Toutes les exécutions de test ont réussi.
1	Une erreur générale s'est produite. Les causes possibles incluent un nom de fichier qui n'existe pas ou une erreur HTTP/réseau.
2	Le test s'est arrêté, car des commandes ou des arguments inconnus ont été fournis.
10	Un ou plusieurs scénarios de test (classes testées ou méthodes de classe) d'une exécution de test n'ont pas réussi.
15	Firebase Test Lab n'a pas pu déterminer si la matrice de test a réussi ou échoué en raison d'une erreur inattendue.
18	L'environnement de test de cette exécution de test n'est pas compatible en raison de dimensions de test incompatibles. Cette erreur peut se produire si le niveau d'API Android sélectionné n'est pas compatible avec le type d'appareil sélectionné.
19	La matrice de test a été annulée par l'utilisateur.
20	Une erreur d'infrastructure de test s'est produite.