Developer Device Platform Device Run pour l'instrumentation Android

Aperçu

Ce produit ou cette fonctionnalité sont soumis aux "Conditions des offres de pré-DG" de la section "Conditions générales du service" des Conditions spécifiques du service. Les produits et fonctionnalités pré-DG sont disponibles "en l'état" et peuvent avoir une compatibilité limitée. Pour en savoir plus, consultez les descriptions des étapes de lancement.

Ce guide explique comment exécuter un test d'instrumentation Android à l'aide de la CLI gcloud beta device-run et comment trouver les résultats dans la console Google Cloud . Il suppose que vous disposez d'un compte et d'un projet Google Cloud .

Si vous migrez de Firebase Test Lab vers Developer Device Platform, consultez notre guide de migration, la traduction des commandes et des options et la compétence de migration pour les agents IA.

Pour utiliser Google Cloud CLI, vous devez fournir l'ID de votre projet Google Cloud . Consultez gcloud beta device-run pour obtenir un résumé des commandes.

Avant de commencer

Ces étapes supposent que vous avez déjà :

1. Vous avez créé un projet Google Cloud .
2. Configurez Developer Device Platform en suivant le guide de démarrage rapide.
3. Vous vous êtes authentifié avec gcloud dans le terminal.
4. Vous avez consulté la présentation de Device Run pour obtenir des informations générales.
5. Créer un test d'instrumentation pour Android

Étape 1 : Configurer l'exécution de votre test

Conseil : Pour afficher toutes les options disponibles pour les commandes submit, exécutez gcloud beta device-run sessions submit instrumentation --help.

Options pour les tests d'instrumentation Android

• Plusieurs appareils : pour exécuter le même test sur plusieurs appareils, fournissez l'option --device avec plusieurs ID d'appareil séparés par une virgule, par exemple --device shiba-34,tokay-36, ou avec plusieurs options --device, chacune spécifiant un ID d'appareil distinct (par exemple, --device shiba-34 --device tokay-36).
• Transférer des fichiers vers l'appareil : transférez des fichiers supplémentaires (tels que des pondérations de modèle de ML, des entrées de test ou des bibliothèques partagées .so) vers l'appareil avant l'exécution à l'aide de --other-files-to-push=SOURCE=DEST,.... SOURCE accepte les chemins d'accès locaux et Cloud Storage (gs://...), et DEST est le chemin d'accès de destination sur l'appareil.
• Extraire des fichiers de l'appareil : extrayez les fichiers ou répertoires générés de l'appareil une fois l'exécution terminée à l'aide de --paths-to-pull=DEVICE_PATH,....
• Bucket Cloud Storage personnalisé : spécifiez le nom d'un bucket Cloud Storage existant (sans schéma ni chemin d'accès gs://) à l'aide de --bucket-name=. Si vous ne spécifiez pas de bucket, la Google Cloud CLI utilise ou crée un bucket par défaut nommé PROJECT_ID-devicerun.
• Nouvelles tentatives de tests irréguliers : définissez le nombre maximal de tentatives par job ou segment pour gérer l'irrégularité : --flaky-test-attempts=3 (par défaut, 1 tentative).
• Environnement et diagnostics de l'appareil : configurez l'orientation de l'appareil (--orientation=portrait ou landscape), les paramètres régionaux (--locale=en-US), la position GPS fictive (--coordinates=LATITUDE,LONGITUDE), l'enregistrement vidéo de l'écran (--video=always ou on-failure), la collecte dumpsys (--dumpsys=always ou on-failure) ou la collecte bugreport (--bugreport=always ou on-failure).
• Libellés : associez des libellés clé-valeur définis par l'utilisateur à la session à l'aide de --labels=KEY=VALUE,....
• Applications supplémentaires : vous pouvez éventuellement spécifier un ou plusieurs fichiers APK, AAB ou APKS à installer avant d'exécuter vos tests à l'aide de l'option --apps=path1,path2,...,path_n. L'ordre que vous spécifiez est l'ordre dans lequel ces applications sont installées.
• Délai avant expiration du test : limitez la durée d'exécution : --instrumentation-timeout=10m (la plage valide est comprise entre 1m et 3h, et la valeur par défaut est 5m).

Exécutions synchrones et asynchrones

Par défaut, la commande d'envoi est bloquante (synchrone). Il attendra la fin du test et affichera un tableau récapitulatif des résultats.

Pour envoyer la session et revenir immédiatement après l'importation des fichiers dans Cloud Storage, ajoutez l'option --async :

gcloud beta device-run sessions submit instrumentation \
  --device shiba-35 \
  --test ./ANDROID_TESTS.apk \
  --async

Un ID de session est renvoyé immédiatement. Vous pouvez ensuite attendre qu'elle se termine à l'aide de la commande sessions wait :

gcloud beta device-run sessions wait SESSION_ID

La commande sera bloquée jusqu'à ce que le job soit terminé.

Plusieurs appareils

Pour exécuter le même test sur plusieurs appareils, fournissez l'option --device avec plusieurs ID d'appareil séparés par une virgule ou avec plusieurs options --device, chacune spécifiant un ID d'appareil distinct :

gcloud beta device-run sessions submit instrumentation \
  --device shiba-34,tokay-36 \
  --test ./ANDROID_TESTS.apk

ou

gcloud beta device-run sessions submit instrumentation \
  --device shiba-34 \
  --device tokay-36 \
  --test ./ANDROID_TESTS.apk

Délai avant la fin du test

Limitez la durée d'exécution de votre test :

gcloud beta device-run sessions submit instrumentation \
  --device shiba-35 \
  --test ./ANDROID_TESTS.apk \
  --instrumentation-timeout=10m

La plage valide est comprise entre 1m et 3h, et la valeur par défaut est 5m.

Versions logicielles

Découvrez et utilisez les packages logiciels et les versions disponibles d'AndroidX Test Orchestrator, et inspectez leurs cycles de vie, leurs versions compatibles et leurs métadonnées avant de configurer les exécutions de test.

Commencez par lister tous les packages logiciels disponibles et leurs versions :

gcloud beta device-run software-versions list

Vous recevez un résultat semblable à celui-ci :

ID                                NAME                              SOFTWARE_TYPE               VERSION  STATE   IS_DEFAULT
androidx-test-orchestrator-1-4-1  AndroidX Test Orchestrator 1.4.1  ANDROIDX_TEST_ORCHESTRATOR  1.4.1    ACTIVE  True
androidx-test-orchestrator-1-6-1  AndroidX Test Orchestrator 1.6.1  ANDROIDX_TEST_ORCHESTRATOR  1.6.1    ACTIVE
xcode-16-4                        Xcode 16.4                        XCODE                       16.4     ACTIVE
xcode-26-2                        Xcode 26.2                        XCODE                       26.2     ACTIVE  True

Ensuite, décrivez un package spécifique à l'aide de son ID de ressource exact dans la liste :

gcloud beta device-run software-versions describe androidx-test-orchestrator-1-4-1

Vous recevez un résultat semblable à celui-ci :

id: androidx-test-orchestrator-1-4-1
isDefault: true
lifecycle:
  state: ACTIVE
name: AndroidX Test Orchestrator 1.4.1
softwareType: ANDROIDX_TEST_ORCHESTRATOR
version: 1.4.1

Maintenant que vous savez quelles versions logicielles sont disponibles, vous pouvez les utiliser dans vos tests avec l'option --orchestrator-version, comme suit :

gcloud beta device-run sessions submit instrumentation \
  --device shiba-35 \
  --test ./ANDROID_TESTS.apk \
  --orchestrator-version=1.4.1

Activer l'outil d'orchestration

Developer Device Platform est compatible avec Android Test Orchestrator, qui vous permet d'exécuter chacun des tests de votre application dans sa propre invocation de Instrumentation.

Lorsque vous utilisez Orchestrator :

• Évitez l'état partagé. Chaque test s'exécute dans sa propre instance Instrumentation. Par conséquent, si vos tests partagent l'état de l'application, la majeure partie de cet état partagé est supprimée du processeur ou de la mémoire de votre appareil après chaque test. Pour supprimer tous les états partagés du processeur et de la mémoire de votre appareil après chaque test, incluez le paramètre clearPackageData comme suit : --additional-test-options clearPackageData=true.

• Isoler les plantages Si un test plante, il ne supprime que sa propre instance de Instrumentation. Cela signifie que vos autres tests continuent de s'exécuter et de fournir des résultats complets.

Android Test Orchestrator est désactivé par défaut dans Developer Device Platform. Pour activer l'Orchestrator et spécifier la version à utiliser lors de l'exécution de test, transmettez la version que vous avez sélectionnée à l'option --orchestrator-version=ORCHESTRATOR_VERSION dans votre commande sessions submit instrumentation, comme suit :

gcloud beta device-run sessions submit instrumentation \
  --device shiba-35 \
  --test ./ANDROID_TESTS.apk \
  --orchestrator-version=1.4.1

Définissez l'option sur auto pour utiliser la version d'Orchestrator par défaut du système.

Remarque : Étant donné que chaque test Orchestrator exécute sa propre instance Instrumentation, l'augmentation des temps d'exécution peut augmenter l'utilisation de votre quota ou le temps facturé, et vous faire dépasser les limites de délai avant expiration de vos appareils. Vous devrez peut-être augmenter le délai avant expiration de l'instrumentation en conséquence avec l'option --instrumentation-timeout.

Étape 2 : Sélectionner des appareils

La CLI device-run permet d'exécuter des tests Android sur les appareils physiques et virtuels disponibles. Pour afficher la liste complète des appareils disponibles, consultez le catalogue d'appareils interactif ou exécutez la commande suivante :

gcloud beta device-run devices list

Exemple de résultat :

ID        MAKE    NAME     MODEL FORM      OS_VERSION CAPACITY  AVAILABILITY  PRODUCTS
tegu-35   Google  Pixel 9a tegu  PHYSICAL  35         MEDIUM    LOW           Automation, Streaming
tokay-34  Google  Pixel 9  tokay PHYSICAL  34         HIGH      HIGH          Automation, Streaming

Consultez le catalogue d'appareils pour savoir comment filtrer cette liste. Pour cibler un appareil spécifique pour votre exécution, utilisez l'ID correspondant (par exemple, tegu-35) dans la commande d'envoi.

Étape 3 : Exécuter le test

Envoyez un APK de test d'instrumentation Android.

Ces options sont obligatoires pour les tests d'instrumentation Android :

• Appareil : spécifiez un appareil à l'aide de --device: --device shiba-35.
• Test : spécifiez l'APK de test à l'aide de --test : --test /path/to/test.apk.

Pour exécuter votre test d'instrumentation, exécutez une commande sessions submit instrumentation semblable à la suivante, en utilisant vos propres ID d'appareil et chemin d'accès au test :

gcloud beta device-run sessions submit instrumentation \
  --device shiba-34 \
  --apps /path/to/app.apk \
  --test /path/to/test.apk

Le dossier du rapport de résultats du job se trouve dans un chemin d'accès Cloud Storage tel que gs://BUCKET_NAME/automation/sessions/SESSION_ID/. Le résultat de la commande affiche un lien semblable à celui-ci : https://console.cloud.google.com/storage/browser/BUCKET_NAME/automation/sessions/SESSION_ID/.

Étape 4 : Utiliser le partitionnement

Pour inclure des tests d'instrumentation Developer Device Platform dans un workflow d'intégration et de livraison continues (CI/CD), vous devez envisager de segmenter vos tests. La segmentation des tests divise un ensemble de tests d'instrumentation en sous-groupes (segments) qui s'exécutent séparément de manière isolée. Developer Device Platform exécute automatiquement chaque segment en parallèle sur plusieurs appareils et effectue l'ensemble des tests plus rapidement.

Attention : Les tests de segmentation peuvent entraîner des coûts supplémentaires. Bien que la segmentation des tests réduise le temps nécessaire à l'exécution de tous vos tests, la surcharge liée au démarrage de votre application sur chaque segment peut augmenter les temps d'exécution sur chaque appareil.

Étape 4.1. Choisir une option de segmentation

Si vos jobs ne comportent qu'un petit nombre de scénarios de test ou si la durée d'exécution totale de tous les scénarios de test n'est pas longue, il n'est pas nécessaire d'utiliser le partitionnement. Si vous avez un grand nombre de scénarios de test ou si la durée totale d'exécution de tous vos scénarios de test est longue, envisagez d'utiliser la segmentation.

Developer Device Platform est compatible avec le partitionnement intelligent et uniforme. Lorsque vous décidez de la manière de segmenter vos tests, tenez compte des options suivantes :

• Si tous les scénarios de test prennent un temps similaire, utilisez la segmentation uniforme en divisant tous les scénarios de test en n segments.

• Lorsque le temps d'exécution des différents scénarios de test varie considérablement, utilisez la segmentation intelligente. Developer Device Platform utilise l'historique des temps d'exécution des tests pour créer différents segments et tente de terminer tous les segments dans un délai similaire.

Remarque : Le nombre de segments est configurable. Par conséquent, lorsque Developer Device Platform exécute de nombreux segments en parallèle, les exécutions de tests peuvent être limitées par la disponibilité des appareils. Pour cette raison, nous vous recommandons de définir un nombre d'appareils inférieur ou égal au nombre de segments dans l'option --device.

Segmentation uniforme

Pour segmenter vos tests avec une segmentation uniforme, incluez les options --sharding-option=uniform et --uniform-sharding-count= dans la commande sessions submit instrumentation comme suit :

gcloud beta device-run sessions submit instrumentation \
    --test path/to/test.apk \
 --device shiba-34,tokay-36 \
    --sharding-option=uniform \
    --uniform-sharding-count=2

Un résultat indiquant Job status: 2 running devrait s'afficher. Le service crée deux jobs, un pour chaque appareil. Comme les entrées des deux jobs sont identiques, le service centralise la validation et ne l'effectue qu'une seule fois.

Une fois l'opération terminée, les deux jobs s'affichent séparément dans le résultat final de la commande :

JOB NAME  EXECUTION NAME  EXECUTION RESULT
job-000   execution-000   PASSED
job-001   execution-000   PASSED

Segmentation intelligente

Pour segmenter vos tests avec la segmentation intelligente, incluez les options --sharding-option=smart, --smart-sharding-max-shard-count=, --smart-sharding-target-duration= (en minutes ou 1h) et --smart-sharding-record-name= dans la commande sessions submit instrumentation comme suit :

gcloud beta device-run sessions submit instrumentation \
    --test path/to/test.apk \
    --device shiba-34,shiba-35,tokay-36 \
    --sharding-option=smart \
    --smart-sharding-max-shard-count=3 \
    --smart-sharding-target-duration=5m \
    --smart-sharding-record-name=test.yaml

Le résultat final doit indiquer que trois jobs ont été exécutés :

Session [session-3cd0564a] finished with result [ERROR].
JOB NAME  EXECUTION NAME  EXECUTION RESULT
job-000   execution-000   PASSED
job-001   execution-000   PASSED
job-002   execution-000   PASSED

Voici un récapitulatif des options de segmentation intelligente utilisées ici :

• --smart-sharding-max-shard-count=SMART_SHARDING_MAX_SHARD_COUNT : spécifiez le nombre maximal de segments à créer pour le segment intelligent. Si cette valeur n'est pas définie ou si elle est définie sur 0, les limites maximales définies par le système sont utilisées. La plage valide est comprise entre 0 et 20 pour les appareils physiques, et entre 0 et 200 pour les appareils virtuels.

• --smart-sharding-target-duration=SMART_SHARDING_TARGET_DURATION : spécifiez le temps d'exécution ciblé (par exemple, 2m, 10m, 1h) par segment pour la segmentation intelligente. La plage valide est comprise entre 2 min et 1 h. Obligatoire lorsque --sharding-option=smart.

• --smart-sharding-record-name=SMART_SHARDING_RECORD_NAME : spécifiez le nom du fichier d'enregistrement de segmentation intelligente, sans l'extension de fichier. Obligatoire lorsque --sharding-option=smart. Ce fichier YAML se trouve dans le bucket de stockage Google Cloudspécifié par --bucket-name dans le répertoire smart-sharding/. Si le fichier n'existe pas, il sera créé automatiquement. Sinon, son contenu sera mis à jour à la fin de la session.

Étape 5 : Explorer et gérer votre test

Pour les modes asynchrone et synchrone de la commande sessions submit instrumentation, vous pouvez utiliser la commande sessions describe pour interroger l'état du job pendant l'exécution ou obtenir le résultat une fois l'opération terminée :

gcloud beta device-run sessions describe SESSION_ID

Le résultat résume les résultats du test et renvoie vers les résultats dans la console Google Cloud . Exemple :

Session SESSION_ID finished with result [FAILED].
Result files are stored at [https://console.cloud.google.com/storage/browser/BUCKET_NAME/automation/sessions/SESSION_ID/].
JOB NAME  EXECUTION NAME  EXECUTION RESULT
job-000   all             FAILED: 2 test cases failed, 5 passed

Utilisez la commande suivante pour lister toutes vos sessions en cours et terminées :

gcloud beta device-run sessions list

Vous recevez un résultat contenant la liste des sessions de votre projet, qui ressemble à ceci :

SESSION_ID                                    START_TIME                STATE
session-4825e153                              2026-07-28T16:38:43.155Z  DONE
session-813ca602                              2026-07-28T22:40:32.415Z  DONE
session-67cd0570                              2026-07-16T08:25:55.474Z  DONE
session-17cc299c                              2026-07-14T14:31:33.649Z  DONE
session-911d0763                              2026-07-09T00:39:02.051Z  DONE
session-4e943fea                              2026-07-15T23:08:32.252Z  DONE
session-0132e458                              2026-08-20T18:33:19.751Z  DONE
session-1077f07b                              2026-07-28T22:35:43.848Z  DONE
session-71b054c6                              2026-07-15T01:15:41.643Z  DONE
session-4f8b2e45                              2026-08-06T23:11:56.161Z  DONE

La commande de liste sessions est compatible avec toutes les options d'option standards de Google Cloud CLI. Exemple :

gcloud beta device-run sessions list --limit 5

Les résultats ressemblent à ce qui suit :

SESSION_ID                            START_TIME                STATE
session-4825e153                      2026-07-28T16:38:43.155Z  DONE
session-813ca602                      2026-07-28T22:40:32.415Z  DONE
93ec2df2-d5bf-4c36-b7f7-c2a4fb0dc3ce  2026-07-03T05:10:58.015Z  DONE
session-67cd0570                      2026-07-16T08:25:55.474Z  DONE
session-17cc299c                      2026-07-14T14:31:33.649Z  DONE

Pour trouver toutes les sessions en cours d'exécution, exécutez la commande suivante :

gcloud beta device-run sessions list --filter RUNNING

Si vous avez des sessions en cours d'exécution, vous verrez des résultats semblables à ceux-ci :

SESSION_ID        START_TIME  STATE
session-d7ff8b81              RUNNING

Sinon, vous recevrez Listed 0 items..

Pour annuler une session en cours, exécutez cette commande avec l'ID de votre session :

gcloud beta device-run sessions cancel SESSION_ID

La commande renvoie immédiatement une réponse, car la session est uniquement marquée pour être annulée. L'annulation s'effectue de manière asynchrone dans le backend.

Si la session est déjà terminée, seul l'état actuel est affiché. Demander l'annulation d'une session terminée ne constitue pas une erreur.

Étapes suivantes

Ensuite, exécutez un fichier exécutable Android ou recherchez et analysez les journaux.