Exécution d'un appareil sur la plate-forme d'appareils pour les développeurs

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 à l'aide de la gcloud beta device-run CLI 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.

Pour utiliser cette Google Cloud CLI, vous devez fournir votre Google Cloud ID de projet.

Avant de commencer

Ces étapes supposent que vous avez déjà créé un Google Cloud projet, suivi les étapes de configuration du guide de démarrage rapide de la plate-forme pour appareils de développement Quickstart et que vous vous êtes authentifié auprès de gcloud dans le terminal.

De plus, vous devez disposer d'un test d'instrumentation Android prêt à être exécuté. Pour obtenir des conseils, consultez Créer des tests instrumentés pour obtenir des conseils.

Vous devez également avoir identifié les ID d'appareil sur lesquels vous souhaitez exécuter vos charges de travail. Pour obtenir des instructions, consultez le catalogue d'appareils.

Conseil : Ajoutez --help à n'importe quelle commande gcloud pour afficher des informations d'utilisation détaillées.

Effectuer un test

Maintenant que vous connaissez les ID des appareils disponibles pour tester votre application, vous pouvez spécifier des appareils à l'aide de la commande gcloud beta device-run sessions submit instrumentation et de l'option --device pour exécuter des tests d'instrumentation.

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

Pour exécuter votre test, exécutez une commande semblable à la suivante, mais avec vos propres ID d'appareil et chemin de test :

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

Le dossier de rapport de résultats du job se trouve dans un chemin Cloud Storage tel que gs://<your_project_id>/automation/sessions/session-id/. Consultez la sortie du test pour obtenir le lien, qui ressemble à : https://console.cloud.google.com/storage/browser/your_project_id/automation/sessions/session-id/.

Configurer l'exécution du test

Maintenant que vous avez exécuté un test, explorez quelques options de configuration :

• Pour exécuter les mêmes tests sur plusieurs appareils, fournissez l'option --device plusieurs fois, par exemple --device shiba-34 --device tokay-36.
• Vous pouvez éventuellement spécifier un ou plusieurs APK à installer avant d'exécuter vos tests à l'aide de l'option --apps=path1,path2,...,path_n. L'ordre dans lequel vous spécifiez ces applications correspond à l'ordre dans lequel elles sont installées.
• Vous devez spécifier votre APK de test avec l'option --test.
• Lorsque vous spécifiez un chemin local avec les options --apps ou --test, la Google Cloud CLI le copie automatiquement dans votre bucket Cloud Storage sous gs://my-project-id/automation/inputs/date_time_four_chars_suffix/ chaque fois que vous exécutez la commande.
• Comme l'importation d'APK volumineux peut prendre du temps, vous pouvez référencer directement vos APK à l'aide de leurs chemins gs:// Cloud Storage pour gagner du temps d'importation.

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

Par défaut, la commande sessions submit instrumentation bloque les résultats de la session, ce qui signifie qu'elle attend la fin de l'exécution du test et génère des résultats semblables à :

Using the default Cloud Storage bucket [gs://<my-project-id>] for input and result files. Will create the bucket if it does not exist.
Uploading [app.apk].
Uploading [test.apk].

Initiated long-running operation [operation-number] to create session.
Creating session [session-id] in location [global].
Result files will be stored at [https://console.cloud.google.com/storage/browser/<my-project-id>/automation/sessions/session-id/].
Waiting for session [session-id] to complete....done.

Session [session-id] finished with result [FAILED].
JOB NAME  EXECUTION NAME  EXECUTION RESULT
job-000   all             FAILED: 2 test cases failed, 5 passed

Pour exécuter la commande de manière asynchrone, incluez l'option --async. Cela permet à la commande de se fermer immédiatement après l'importation de fichiers dans Cloud Storage et l'impression de l'ID d'opération et de l'ID de session. Vous pouvez utiliser la commande d'attente des opérations et l'ID d'opération pour attendre l'exécution. Elle se bloque jusqu'à ce que le job soit terminé :

gcloud beta device-run operations wait your_operation_id

Utiliser le partitionnement

Pour inclure la plate-forme pour appareils de développement dans un workflow d'intégration et de livraison continues (CI/CD), vous devez envisager de partitionner vos tests. Le partitionnement des tests divise un ensemble de tests en sous-groupes (partitions) qui s'exécutent séparément de manière isolée. La plate-forme pour appareils de développement 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 être plus coûteux. 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.

Options de partitionnement

Si vos jobs ne comportent qu'un petit nombre de scénarios de test ou si le temps d'exécution total de tous les scénarios de test n'est pas long, il n'est pas nécessaire d'utiliser le partitionnement. Si vous avez un grand nombre de scénarios de test ou si le temps d'exécution total de tous leurs scénarios de test est long, envisagez d'utiliser le partitionnement.

La plate-forme pour appareils de développement 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 le temps d'exécution des différents scénarios de test varie considérablement, utilisez le partitionnement intelligent. La plate-forme pour appareils de développement utilise l'historique du temps d'exécution des tests pour créer différentes partitions et tente de terminer toutes les partitions dans une durée similaire.

Partitionnement uniforme

Pour partitionner vos tests avec le partitionnement 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 \
    --device tokay-36 \
    --sharding-option=uniform \
    --uniform-sharding-count=2

Vous devriez voir une sortie 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 la sortie finale 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 le 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 \
    --device shiba-35 \
    --device 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 une sortie finale 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écapitulatif 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-max-shard-count : spécifie le nombre maximal de partitions à créer. Le nombre d'appareils spécifié dans l'option --device doit être inférieur ou égal à cette valeur.

• --smart-sharding-target-duration=SMART_SHARDING_TARGET_DURATION : spécifiez le temps d'exécution cible (par exemple, 2 m, 10 m, 1 h) par partition pour le partitionnement intelligent. La plage valide est comprise entre 2 m et 1 h. 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.

Explorer et gérer l'exécution de 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>

La sortie 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/your_project_id-devicerun/automation/sessions/session-id/].
JOB NAME  EXECUTION NAME  EXECUTION RESULT
job-000   all             FAILED: 2 test cases failed, 5 passed

Exécutez la commande suivante pour afficher la liste de toutes vos sessions en cours d'exécution et terminées :

gcloud beta device-run sessions list

Recevez une sortie contenant la liste des sessions de votre projet, semblable à :

SESSION_ID                                    START_TIME                STATE
session-4825e153                              2026-07-28T16:38:43.155Z  DONE
session-813ca602                              2026-07-28T22:40:32.415Z  DONE

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

gcloud beta device-run sessions cancel your_session_id

Étape suivante

Ensuite, recherchez et analysez les journaux.