Exécution d'appareils sur la plate-forme Developer Device pour Android

Aperçu

Ce produit ou cette fonctionnalité est soumis aux "Conditions des offres pré-DG" de la section "Conditions d'utilisation 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 ou un exécutable Android autonome à l'aide de la CLI gcloud beta device-run et comment trouver vos résultats dans la Google Cloud console. Il suppose que vous disposez d'un Google Cloud compte et d'un projet.

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

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

Avant de commencer

Ces étapes supposent que vous avez déjà effectué les opérations suivantes :

1. Créer un Google Cloud projet.
2. Configurer Developer Device Platform en suivant le guide de démarrage rapide.
3. Vous authentifier auprès de gcloud dans le terminal.
4. Consulter la présentation de Device Run pour obtenir des informations générales.
5. Créer un test d'instrumentation pour Android ou préparer un exécutable Android autonome (tel qu'un binaire C++ compilé, un exécuteur de benchmark ou un script shell).

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

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

Maintenant que vous avez exécuté une session, explorez quelques options de configuration :

Options pour les tests d'instrumentation et les exécutables

• Plusieurs appareils : pour exécuter le même test ou le même exécutable 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).
• Envoyer des fichiers à l'appareil : envoyez des fichiers supplémentaires (tels que des pondérations de modèle ML, entrées de test ou .so bibliothèques partagées) à l'appareil avant l'exécution à l'aide de --other-files-to-push=SOURCE=DEST,.... SOURCE est compatible avec les chemins d'accès locaux et Cloud Storage (gs://...), et DEST correspond au 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 un nom de 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 test instable : définissez le nombre maximal de tentatives par job ou segment pour gérer l'instabilité : --flaky-test-attempts=3 (la valeur par défaut est 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), l'emplacement GPS simulé (--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,....

Options de test d'instrumentation

• 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' --apps=path1,path2,...,path_n option. L'ordre dans lequel vous spécifiez ces applications correspond à l'ordre dans lequel elles 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).

Options d'exécutable Android

• Arguments exécutables : transmettez des arguments de ligne de commande à l'exécutable à l'aide de --executable-args=ARG,... sous forme de liste séparée par des virgules ou en répétant l' option. Chaque élément devient un argument. Vous devez donc réécrire les lignes de commande séparées par des espaces sous forme de liste séparée par des virgules (par exemple, --executable-args="--input=a.file,--threads=4"). Pour transmettre un argument qui contient lui-même une virgule, ajoutez le préfixe ^SEP^ à la valeur pour spécifier un séparateur différent (par exemple, --executable-args="^;^--shape=1,224,224,3;--threads=4").
• Variables d'environnement : définissez des variables d'environnement pour le processus exécutable sur l'appareil à l'aide de --executable-env-vars=KEY=VALUE,... (par exemple, --executable-env-vars=LD_LIBRARY_PATH=/data/local/tmp/lib).
• Délai avant expiration de l'exécutable : limitez la durée d'exécution de l'exécutable : --executable-timeout=10m (la plage valide est comprise entre 1m et 3h, et la valeur par défaut est 5m, à l'exclusion du temps de préparation et de nettoyage de l'appareil).

Exécutions synchrones et asynchrones

Par défaut, la commande submit est bloquante (synchrone). Elle attend la fin du test ou de l'exécutable, puis affiche un tableau récapitulatif des résultats.

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

Test d'instrumentation Android

Pour un :

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

Exécutable Android

gcloud beta device-run sessions submit android-executable \
  --device shiba-35 \
  --executable ./MY_EXECUTABLE \
  --async

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

gcloud beta device-run sessions wait SESSION_ID

La commande se bloque jusqu'à ce que le job soit terminé.

Plusieurs appareils

Pour exécuter le même test ou le même exécutable 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.

Test d'instrumentation Android

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

Exécutable Android

gcloud beta device-run sessions submit android-executable \
  --device shiba-34,tokay-36 \
  --executable ./MY_EXECUTABLE

ou

gcloud beta device-run sessions submit android-executable \
  --device shiba-34 \
  --device tokay-36 \
  --executable ./MY_EXECUTABLE

Délai avant expiration du test et de l'exécutable

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

Test d'instrumentation Android

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

Exécutable Android

gcloud beta device-run sessions submit android-executable \
  --device shiba-35 \
  --executable ./MY_EXECUTABLE \
  --executable-timeout=10m

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

Versions logicielles

Découvrez et utilisez les packages logiciels et les versions de AndroidX Test Orchestrator disponibles, et inspectez leurs cycles de vie, les versions compatibles et les 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 recevrez 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

Décrivez ensuite 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 recevrez 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 exécutions de test 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

Pour en savoir plus, consultez la section Activer Orchestrator.

Activer Orchestrator

Pour les tests d'instrumentation, 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, vous :

• Évitez l'état partagé. Chaque test s'exécute dans sa propre instance Instrumentation. Ainsi, 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 tout l'état partagé du processeur et de la mémoire de votre appareil après chaque test, incluez le clearPackageData paramètre comme suit : --additional-test-options clearPackageData=true

• Isolez 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 fournissent des résultats de test complets.

Android Test Orchestrator est désactivé par défaut dans Developer Device Platform. Pour activer 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 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 Orchestrator par défaut du système.

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

Étape 2 : Sélectionner des appareils

À l'aide de la CLI device-run, les tests et exécutables Android peuvent être exécutés sur les appareils physiques et virtuels disponibles. Pour afficher la liste complète des appareils disponibles, consultez le catalogue interactif des appareils 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 des appareils pour découvrir comment filtrer cette liste. Pour cibler un appareil spécifique pour votre exécution, utilisez son ID correspondant (par exemple, tegu-35) dans la commande submit.

Étape 3 : Exécuter votre test ou votre exécutable

Vous pouvez envoyer un APK de test d'instrumentation Android ou un exécutable Android autonome.

Exécuter un test d'instrumentation

Notez que 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 sessions submit instrumentation commande 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

Exécuter un exécutable Android

Pour exécuter un exécutable autonome (tel qu'un binaire C++ compilé, un exécuteur de benchmark de machine learning sur l'appareil comme LiteRT ou un script shell) directement sur un appareil Android sans l'empaqueter dans un APK, utilisez la sessions submit android-executable commande.

Notez que ces options sont obligatoires pour les exécutables Android :

• Appareil : spécifiez un appareil à l'aide de --device : --device shiba-35
• Exécutable : spécifiez le chemin d'accès local ou Cloud Storage à l'exécutable à l'aide de --executable : --executable /path/to/my_executable

Pour exécuter votre exécutable, exécutez une commande semblable à la suivante, en utilisant vos propres ID d'appareil et chemin d'accès à l'exécutable :

gcloud beta device-run sessions submit android-executable \
  --device shiba-34 \
  --executable /path/to/my_executable \
  --executable-args="--input=/data/local/tmp/file.name,--threads=4" \
  --other-files-to-push=/path/to/model.tflite=/data/local/tmp/model.tflite \
  --paths-to-pull=/data/local/tmp/output

Le dossier de 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/. Consultez le résultat de la commande pour obtenir le lien, qui ressemble à : https://console.cloud.google.com/storage/browser/BUCKET_NAME/automation/sessions/SESSION_ID/.

Étape 4 : Utiliser le partitionnement

Pour inclure les tests d'instrumentation de Developer Device Platform dans un workflow d'intégration continue et de livraison continue (CI/CD), vous devez envisager de partitionner vos tests. Le partitionnement des tests divise un ensemble de tests d'instrumentation en sous-groupes (partitions) qui s'exécutent séparément de manière isolée. Developer Device Platform exécute automatiquement chaque partition en parallèle à l'aide de plusieurs appareils et effectue l'ensemble des tests en moins de temps.

Attention : Le partitionnement des tests peut entraîner des coûts plus élevés. Bien que le partitionnement 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 partition peut augmenter les durées individuelles des appareils.

Étape 4.1 : Choisir une option de partitionnement

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 d'exécution totale de tous leurs scénarios de test est longue, envisagez d'utiliser le partitionnement.

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

• Si tous les scénarios de test prennent un temps similaire, utilisez le partitionnement uniforme en divisant tous les scénarios de test en n partitions.

• Lorsque la durée d'exécution des différents scénarios de test varie considérablement, utilisez le partitionnement intelligent. Developer Device Platform utilise l'historique de la durée d'exécution des tests pour créer différentes partitions et tente de terminer toutes les partitions dans une durée similaire.

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

Partitionnement uniforme

Pour segmenter vos tests avec un partitionnement uniforme, incluez les indicateurs --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

Vous devriez voir un résultat indiquant Job status: 2 running. Le service crée deux jobs, un pour chaque appareil. Étant donné que les entrées des deux jobs sont identiques, le service centralise la validation et ne l'effectue qu'une seule fois.

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

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

Partitionnement intelligent

Pour partitionner vos tests avec un partitionnement intelligent, 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

Vous devriez voir un résultat final indiquant 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ésumé des options de partitionnement intelligent utilisées ici :

• --smart-sharding-max-shard-count=SMART_SHARDING_MAX_SHARD_COUNT : spécifiez le nombre maximal de partitions à créer pour le partitionnement intelligent. Si cette option n'est pas définie ou 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 la durée d'exécution cible (par exemple, 2m, 10m, 1h) par partition pour le partitionnement intelligent . La plage valide est comprise entre 2m et 1h. Obligatoire lorsque --sharding-option=smart.

• --smart-sharding-record-name=SMART_SHARDING_RECORD_NAME : spécifiez le nom du fichier d'enregistrement du partitionnement intelligent, sans l'extension de fichier. Obligatoire lorsque --sharding-option=smart. Ce fichier YAML se trouve dans le Google Cloud bucket Storage spécifié par --bucket-name sous le smart-sharding/ répertoire. Si le fichier n'existe pas, il est créé automatiquement. Sinon, son contenu est mis à jour une fois la session terminée.

Étape 5 : Explorer et gérer votre exécution de test

Pour les modes asynchrone et synchrone des sessions submit instrumentation et sessions submit android-executable commandes, vous pouvez utiliser la sessions describe commande 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écapitule les résultats des tests et fournit des liens vers les résultats dans la Google Cloud console. 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 d'exécution et terminées :

gcloud beta device-run sessions list

Vous recevrez un résultat contenant la liste des sessions de votre projet, semblable à celui-ci :

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 standard de la Google Cloud CLI. Exemple :

gcloud beta device-run sessions list --limit 5

Résultat :

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 le message Listed 0 items.

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

gcloud beta device-run sessions cancel SESSION_ID

La commande renvoie immédiatement une réponse, car la session est uniquement marquée comme devant ê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 imprimé. La demande d'annulation d'une session terminée n'est pas une erreur.

Étape suivante

Ensuite, recherchez et analysez les journaux.