Migrer de Firebase Test Lab et Flank vers la plate-forme Developer Device avec l'IA

Cette compétence permet de traduire les configurations et les workflows d'exécution de tests hérités (à partir de Flank ou gcloud firebase test) vers la surface de la CLI gcloud beta device-run moderne et axée sur les ressources.

Mappage de la structure des commandes et des ressources

La CLI Device Run organise les commandes par ressource : devices, software-versions et sessions :

1. Catalogue d'appareils (devices)

  • List Devices (Lister les appareils) :
    • Ancienne : gcloud firebase test android/ios models list
    • Nouveau : gcloud beta device-run devices list [--filter="..."]
    • Exemple : gcloud beta device-run devices list --filter="platform:android"
  • Décrivez l'appareil :
    • Ancien : gcloud firebase test android/ios models describe {MODEL}
    • Nouveau : gcloud beta device-run devices describe {DEVICE}
    • Exemple : gcloud beta device-run devices describe redfin-30
  • Vérifier les capacités des appareils et la disponibilité du parc :
    • Ancien : gcloud firebase test android/ios list-device-capacities
    • Nouveau : Intégré directement à la ressource Device (availability.capacity et availability.available). Inspectez à l'aide de gcloud beta device-run devices describe {DEVICE} ou filtrez directement avec gcloud beta device-run devices list --filter="availability.capacity=CAPACITY_HIGH".

2. Versions logicielles (software-versions)

  • Lister les versions logicielles compatibles (Xcode et Android Test Orchestrator) :
    • Ancien : gcloud firebase test ios xcode-versions list
    • Nouveau : gcloud beta device-run software-versions list
  • Décrivez la version du logiciel :
    • Nouveau : gcloud beta device-run software-versions describe {SOFTWARE_VERSION}
    • Exemple : gcloud beta device-run software-versions describe xcode-16-4

3. Sessions d'automatisation (sessions)

  • Envoyer l'instrumentation Android :
    • Ancien : gcloud firebase test android run --type=instrumentation ...
    • Nouveau : gcloud beta device-run sessions submit instrumentation ...
  • Envoyer un XCTest iOS :
    • Ancien : gcloud firebase test ios run --type=xctest ...
    • Nouveau : gcloud beta device-run sessions submit xctest ...
  • Attendre la fin de la session :
    • Ancienne : blocage synchrone de la CLI uniquement
    • Nouveau : gcloud beta device-run sessions wait {SESSION}
  • Décrire / Inspecter la session :
    • Ancienne : afficher le lien Web dans la console Firebase / les résultats des outils Cloud
    • Nouveau : gcloud beta device-run sessions describe {SESSION} [--full]
  • Lister les sessions passées :
    • Ancienne : afficher l'historique de la matrice dans la console Web
    • Nouveau : gcloud beta device-run sessions list
  • Annuler la session :
    • Ancienne : console Web uniquement (pas de commande CLI)
    • Nouveau : gcloud beta device-run sessions cancel {SESSION}

Table de référence pour le mappage des indicateurs

Le tableau suivant mappe les paramètres de l'ancien Firebase Test Lab et de Flank avec leurs équivalents compatibles dans gcloud beta device-run :

Type de test Groupe de caractéristiques Ancien paramètre (firebase / Flank) Paramètre cible (device-run) Format / Logique de conversion
Communs (Android et iOS) Paramètres et composants principaux Flanc --project --project Indicateur global Google Cloud (--project=PROJECT_ID) ou configuration active de Google Cloud CLI.
Communs (Android et iOS) Paramètres et composants principaux --client-details --labels Dictionnaire de paires clé=valeur.
Communs (Android et iOS) Configuration et ciblage des appareils --device model={M},version={V} --device={M}-{V} Associe le modèle et la version de l'OS à une chaîne d'ID --device. Accepte une liste de plusieurs appareils séparés par une virgule dans un seul indicateur (par exemple, --device=mediumphone-arm-32,shiba-36).
Communs (Android et iOS) Contrôle de l'exécution et instabilité --async --async Maps 1:1. La commande reste synchrone par défaut. Transmettez-la pour renvoyer immédiatement. Surveillez ou attendez avec gcloud beta device-run sessions wait <SESSION_ID>.
Communs (Android et iOS) Contrôle de l'exécution et instabilité --num-flaky-test-attempts {R} --flaky-test-attempts {A} Nombre entier. Convertissez le nombre de tentatives $R$ en limite de tentatives totales : $A = R + 1$ (par défaut, la valeur est 1).
Communs (Android et iOS) Contrôle de l'exécution et instabilité N/A --flaky-test-parallel-retry Booléen : Indique s'il faut réessayer les échecs de test en parallèle (par défaut, ils sont séquentiels).
Communs (Android et iOS) Contrôle de l'exécution et instabilité N/A --flaky-test-retry-level String. Niveau de réessai : shard ou test (shard par défaut).
Communs (Android et iOS) Sortie et stockage --results-bucket --bucket-name Bucket dans lequel les artefacts de sortie des tests sont importés (gs://[PROJECT_ID]-devicerun par défaut).
Communs (Android et iOS) Sortie et stockage --results-dir Géré automatiquement La définition de sous-répertoires personnalisés n'est pas prise en charge. Tous les artefacts de test sont automatiquement organisés sous automation/sessions/{session_id}/ dans le bucket spécifié par --bucket-name.
Communs (Android et iOS) Sortie et stockage --record-video --video Valeurs valides : always ou on-failure.
Communs (Android et iOS) Sortie et stockage --directories-to-pull --paths-to-pull Liste des chemins d'accès à extraire de l'appareil après l'exécution.
Android courant Paramètres et composants principaux --app --apps Liste. Si plusieurs APK/AAB d'application sont fournis, transmettez-les tous à --apps.
Android courant Paramètres et composants principaux --additional-apks --apps Liste. Fusionnez les valeurs de liste supplémentaires directement dans la liste --apps principale.
Android courant Paramètres et composants principaux --obb-files --other-files-to-push Dictionnaire au format SOURCE=DEST. Transférez les fichiers OBB directement vers le chemin d'accès de l'appareil (/sdcard/Android/obb/{package_name}/).
Android courant Paramètres et composants principaux --other-files --other-files-to-push Dictionnaire au format SOURCE=DEST.
Android courant Configuration et ciblage des appareils --device locale={L} --locale={L} Associe les paramètres régionaux de l'appareil au drapeau --locale de premier niveau (language-region, par exemple --locale=en-US).
Android courant Configuration et ciblage des appareils --device orientation={O} --orientation={O} Mappe l'orientation de l'appareil au flag --orientation de premier niveau (portrait ou landscape).
Android courant Configuration et ciblage des appareils N/A --coordinates Coordonnées de position fictive (latitude,longitude, par exemple, 37.4220,-122.0841).
Android courant Contrôle de l'exécution et instabilité --grant-permissions Paramètres par défaut automatisés Automatisé : Les autorisations d'exécution sont accordées automatiquement par défaut (équivalent à --grant-permissions=all).|
Android courant Sortie et stockage N/A --dumpsys Collectez dumpsys à partir de l'appareil (always ou on-failure).
Android courant Sortie et stockage N/A --bugreport Collectez le rapport de bug depuis l'appareil (always ou on-failure).
Instrumentation Android Paramètres et composants principaux --type=instrumentation sessions submit instrumentation La structure des sous-commandes détermine le type de test au lieu d'un indicateur --type.
Instrumentation Android Paramètres et composants principaux --test --test Chemin d'accès au fichier binaire contenant les tests d'instrumentation.
Instrumentation Android Contrôle de l'exécution et instabilité --timeout --instrumentation-timeout Durée (par exemple, 10m, 20s, 1h). Plage valide : de 1m à 3h (par défaut, 5m).
Instrumentation Android Contrôle de l'exécution et instabilité --num-uniform-shards {N} --sharding-option=uniform
--uniform-sharding-count={N} 		La configuration des indicateurs active une stratégie de partitionnement uniforme (plage de nombre valide : 1 à 20 partitions physiques, 1 à 200 partitions virtuelles).
Instrumentation Android Contrôle de l'exécution et instabilité Flanc --shard-time {S} --sharding-option=smart
--smart-sharding-target-duration={S} 		Active le partitionnement intelligent avec le temps d'exécution cible (par exemple, 2m, 10m, 1h). Plage valide : de 2m à 1h.
Instrumentation Android Contrôle de l'exécution et instabilité Flanc --smart-flank-gcs-path --smart-sharding-record-name={name}
--bucket-name={bucket} 		Nom du fichier YAML d'enregistrement du partitionnement (sans l'extension) dans --bucket-name sous automation/smart-sharding/.
Instrumentation Android Contrôle de l'exécution et instabilité Flanc --max-test-shards {N} --smart-sharding-max-shard-count={N} Correspond à une limite de partition maximale lorsque le partitionnement intelligent est activé (0 à 20 partitions physiques, 0 à 200 partitions virtuelles).
Instrumentation Android Exécuteur de tests et cibles --test-runner-class --test-runner-class Classe de programme d'exécution complète.
Instrumentation Android Exécuteur de tests et cibles --test-targets --test-targets Dictionnaire prenant en charge les clés telles que package, notPackage, class, notClass, annotation, notAnnotation et size. Les formats tels que testfile ou notTestfile ne seront pas acceptés.
Instrumentation Android Exécuteur de tests et cibles --use-orchestrator --orchestrator-version Accepte auto (orchestrateur par défaut) ou une chaîne de version spécifique (par exemple, 1.6).
Instrumentation Android Exécuteur de tests et cibles --environment-variables --additional-test-options Dictionnaire des options transmises au programme d'exécution des tests. Les formats acceptés dans --test-targets ne sont pas autorisés ici.
Problèmes courants sur iOS Paramètres et composants principaux --additional-ipas --additional-apps Liste des fichiers .ipa à installer sur l'appareil avant l'exécution du test.
Problèmes courants sur iOS Paramètres et composants principaux --other-files --other-files-to-push Dictionnaire au format SOURCE=BUNDLE_ID:DEVICE_PATH.
Problèmes courants sur iOS Sortie et stockage --directories-to-pull --paths-to-pull Liste des fichiers ou répertoires à extraire après le test au format BUNDLE_ID:DEVICE_PATH.
iOS XCTest uniquement Paramètres et composants principaux --type=xctest sessions submit xctest La structure des sous-commandes détermine le type de test au lieu d'un indicateur --type.
iOS XCTest uniquement Paramètres et composants principaux --test --test Chemin d'accès au fichier ZIP contenant l'application iOS et les fichiers XCTest.
iOS XCTest uniquement Contrôle de l'exécution et instabilité --timeout --xctest-timeout Durée maximale autorisée pour l'exécution de XCTest (plage valide : de 1m à 1h, valeur par défaut : 5m).
iOS XCTest uniquement Exécuteur de tests et cibles --xctestrun-file --xctestrun-file Chemin d'accès au fichier .xctestrun personnalisé.
iOS XCTest uniquement Exécuteur de tests et cibles --xcode-version --xcode-version ID ou chaîne de version du catalogue Xcode à utiliser (par exemple, xcode-16-4 ou 16.4). Interrogez à l'aide de software-versions list.

Conseils pratiques pour la traduction

Suivez ces consignes pour traduire les configurations Firebase Test Lab et Flank en configurations device-run :

1. Caractéristiques de l'appareil

Dans gcloud beta device-run, --device accepte une liste de chaînes d'ID de modèle et de version séparées par une virgule. Contrairement à Firebase, qui nécessitait un indicateur --device par appareil, device-run permet de spécifier plusieurs appareils dans un seul indicateur. Les paramètres régionaux, l'orientation et les coordonnées fictives de l'appareil sont spécifiés à l'aide d'indicateurs de premier niveau distincts :

  • ❌ --device model=MediumPhone.arm,version=32,locale=en,orientation=portrait
  • ✅ --device=mediumphone-arm-32 --locale=en-US --orientation=portrait

2. Dictionnaires et listes

Convertissez les flags séparés par une virgule en listes (--apps, --paths-to-pull) ou en dictionnaires clé-valeur (--other-files-to-push, --additional-test-options) :

  • ❌ --other-files /sdcard/file1.txt=local/file1.txt,/sdcard/file2.txt=local/file2.txt
  • ✅ --other-files-to-push local/file1.txt=/sdcard/file1.txt,local/file2.txt=/sdcard/file2.txt

3. Stratégies de segmentation

  • Segmentation uniforme :
    • Définissez --sharding-option=uniform.
    • Définissez --uniform-sharding-count={count} (de 1 à 20 pour les cartes physiques, de 1 à 200 pour les cartes virtuelles).
  • Segmentation intelligente :
    • Définissez --sharding-option=smart.
    • Définissez --smart-sharding-target-duration={duration} (par exemple, 2m, 10m, 1h ; plage valide : de 2m à 1h).
    • Définissez --smart-sharding-record-name={record_name} (pointe vers l'enregistrement de suivi YAML dans --bucket-name sous automation/smart-sharding/).
    • Définissez --smart-sharding-max-shard-count={max_count} (limite maximale facultative : de 0 à 20 pour les produits physiques, de 0 à 200 pour les produits virtuels).

4. Exécution asynchrone

  • Async & Waiting : lorsque --async est spécifié, la CLI renvoie immédiatement l'ID de session créé. Vous pouvez attendre la fin de la session dans les workflows CI/CD à l'aide de : gcloud beta device-run sessions wait <SESSION_ID>

5. Configuration YAML déclarative (--flags-file)

Pour les configurations complexes ou les équipes qui préfèrent gérer des fichiers contrôlés par version plutôt que de longues commandes de terminal, gcloud fournit un préprocesseur d'arguments --flags-file universel (voir $ gcloud topic flags-file) :

gcloud beta device-run sessions submit instrumentation --flags-file=device-run-flags.yaml

!REMARQUE Pourquoi les clés nécessitent-elles -- ? gcloud injecte les clés YAML directement dans l'analyseur CLI en tant que indicateurs de ligne de commande. Chaque clé du fichier YAML doit être précédée de -- (par exemple, --device:, --apps:). Sans --, gcloud les rejette en tant qu'arguments positionnels non reconnus.

Voici un exemple illustrant les indicateurs de liste et de dictionnaire à valeurs multiples :

# device-run-flags.yaml
--device:
  -   mediumphone-arm-32
  -   shiba-36
--apps:
  -   app-debug.apk
  -   test-helper.apk
--test: app-debug-androidTest.apk
--bucket-name: my-bucket
--sharding-option: smart
--smart-sharding-target-duration: 2m
--smart-sharding-record-name: timing-record
--paths-to-pull:
  -   /sdcard/screenshots
  -   /sdcard/coverage.ec
--additional-test-options:
  coverage: "true"
  clearPackageData: "true"

Exemples de traductions

Utilisez ces exemples pour traduire vos configurations Firebase Test Lab et Flank existantes en configurations d'exécution sur l'appareil.

Firebase Test Lab vers l'exécution sur l'appareil

firebase cmd :

gcloud firebase test android run \
  --app=app-debug.apk \
  --test=app-debug-androidTest.apk \
  --device model=shiba,version=36 \
  --timeout=5m \
  --num-flaky-test-attempts=2 \
  --directories-to-pull=/sdcard/screenshots \
  --environment-variables coverage=true

Traduction :

gcloud beta device-run sessions submit instrumentation \
  --device=shiba-36 \
  --apps=app-debug.apk \
  --test=app-debug-androidTest.apk \
  --instrumentation-timeout=5m \
  --flaky-test-attempts=3 \
  --paths-to-pull=/sdcard/screenshots \
  --additional-test-options coverage=true

Configurations Flank pour l'exécution sur l'appareil

flank options (flank.yml) :

gcloud:
  app: app-debug.apk
  test: app-debug-androidTest.apk
  device:
    -   model: mediumphone-arm
      version: 32
  shard-time: 120
  smart-flank-gcs-path: gs://my-bucket/automation/smart-sharding/timing-record.yaml

Traduction :

Traduisez directement en commande CLI moderne :

gcloud beta device-run sessions submit instrumentation \
  --device=mediumphone-arm-32 \
  --apps=app-debug.apk \
  --test=app-debug-androidTest.apk \
  --bucket-name=my-bucket \
  --sharding-option=smart \
  --smart-sharding-target-duration=2m \
  --smart-sharding-record-name=timing-record

Option 2 : Fichier de signalisation YAML déclaratif (--flags-file)

Si vous préférez gérer les configurations dans un fichier YAML avec contrôle des versions plutôt que dans des chaînes de script shell, utilisez la fonctionnalité --flags-file intégrée de gcloud :

# device-run-flags.yaml
# Note: gcloud requires keys to start with '--'
--device:
  -   mediumphone-arm-32
--apps:
  -   app-debug.apk
--test: app-debug-androidTest.apk
--bucket-name: my-bucket
--sharding-option: smart
--smart-sharding-target-duration: 2m
--smart-sharding-record-name: timing-record

Envoyer avec la CLI :

gcloud beta device-run sessions submit instrumentation --flags-file=device-run-flags.yaml

(Vous pouvez également ajouter ou remplacer des indicateurs sur la ligne de commande, par exemple en ajoutant --async.)

Découverte du catalogue d'appareils

listing & inspecting devices :

# List all available Android devices
gcloud beta device-run devices list --filter="platform:android"

# Filter devices with high fleet capacity (replaces legacy list-device-capacities)
gcloud beta device-run devices list --filter="availability.capacity=CAPACITY_HIGH"

# Describe a specific device (OS versions, form factors, orientation, locales, capacity)
gcloud beta device-run devices describe redfin-30

Cycle de vie de session de bout en bout dans la CI/CD

submitting, waiting, and inspecting sessions :

# 1. Submit asynchronously and capture session ID
SESSION_ID=$(gcloud beta device-run sessions submit instrumentation \
  --apps=app-debug.apk \
  --test=app-debug-androidTest.apk \
  --device=mediumphone-arm-32 \
  --async \
  --format="value(name)")

# 2. Wait for session completion in CI/CD pipeline
gcloud beta device-run sessions wait "$SESSION_ID"

# 3. Describe session summary (or pass --full for complete details)
gcloud beta device-run sessions describe "$SESSION_ID"

# 4. Cancel a running session if aborted
gcloud beta device-run sessions cancel "$SESSION_ID"