Exécution d'un appareil Developer Device Platform pour iOS

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 XCTest iOS à l'aide de la gcloud alpha 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.

Si vous migrez de Firebase Test Lab vers la plate-forme d'appareils pour développeurs, consultez notre guide de migration, traduction des commandes et des options, et compétence de migration pour les agents d'IA.

Pour utiliser la CLI device-run, vous devez fournir l'ID de votre Google Cloud projet. Consultez gcloud alpha 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 la plate-forme d'appareils pour développeurs en suivant le guide de démarrage rapide.
3. Vous authentifier auprès de gcloud dans le terminal.
4. Consulter la présentation de l'exécution sur un appareil pour obtenir des informations générales.
5. Compiler vos tests et les empaqueter dans un fichier ZIP.

Étape 1 : Configurer l'exécution du test

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

Vous pouvez personnaliser l'exécution de votre test à l'aide des options facultatives suivantes (bien qu'au moins une instance de l'option --device soit requise) :

• Plusieurs appareils : spécifiez l'option --device plusieurs fois pour exécuter le même test sur plusieurs appareils simultanément : --device iphonese3-18-4 --device iphonese3-26-3 ou --device iphonese3-18-4,iphonese3-26-3
• Applications supplémentaires : installez un ou plusieurs packages .ipa supplémentaires avant de lancer le test à l'aide de --additional-apps: --additional-apps=/path/to/AdditionalApp.ipa
• Fichier .xctestrun personnalisé : transmettez un fichier de configuration personnalisé avec --xctestrun-file : --xctestrun-file=/path/to/CustomTests.xctestrun
• Versions Apple Xcode : accédez directement aux versions Xcode compatibles avec la CLI à l'aide de l'option --xcode-version, par exemple : --xcode-version=xcode-16-4
• Délai avant la fin du test : limitez la durée d’exécution : --xctest-timeout=10m (la plage valide est comprise entre 1m et 1h, et la valeur par défaut est 5m).
• Libellés : associez des métadonnées définies par l'utilisateur à la session : --labels=env=staging,owner=my-team
• Paramètres régionaux : définissez les paramètres régionaux de l'appareil : --locale=en-US
• Transférer des fichiers vers l'appareil : transférez des fichiers vers le conteneur de données de l'application avant l'exécution du test : --other-files-to-push=/tmp/data.txt=com.example.app:/Documents/data.txt
• Extraire des fichiers de l'appareil : extrayez des fichiers du conteneur de données de l'application après l'exécution du test : --paths-to-pull=com.example.app:/Documents/output.txt
• Nouvelles tentatives de test irrégulier : définissez le nombre maximal de tentatives pour relancer les tests irréguliers : --flaky-test-attempts=3 (la valeur par défaut est 1 tentative).
• Bucket Cloud Storage personnalisé : spécifiez un bucket Cloud Storage personnalisé pour les entrées et les sorties : --bucket-name=my-custom-bucket (la valeur par défaut est PROJECT_ID-devicerun).
• Étant donné que l'importation de fichiers ZIP ou IPA volumineux peut prendre du temps, vous pouvez référencer directement vos fichiers à l'aide de leurs chemins gs:// Cloud Storage pour gagner du temps.

Exécutions synchrones et asynchrones

Par défaut, la commande d'envoi est bloquante (synchrone). Elle attend la fin du test et 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 :

gcloud alpha device-run sessions submit xctest \
  --device iphonese3-18-4 \
  --test ./IOS_TESTS.zip \
  --async

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

gcloud alpha 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 sur plusieurs appareils, fournissez l'option --device avec plusieurs ID d'appareil séparés par des virgules ou avec plusieurs options --device, chacune spécifiant un ID d'appareil distinct.

Séparés par des virgules

gcloud alpha device-run sessions submit xctest \
  --device iphonese3-18-4,iphonese3-26-3 \
  --test ./IOS_TESTS.zip

Plusieurs options

gcloud alpha device-run sessions submit xctest \
  --device iphonese3-18-4 \
  --device iphonese3-26-3 \
  --test ./IOS_TESTS.zip

Délai avant la fin du test

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

gcloud alpha device-run sessions submit xctest \
  --device iphonese3-18-4 \
  --test ./IOS_TESTS.zip \
  --xctest-timeout=10m

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

Versions logicielles

Découvrez et utilisez les packages logiciels et les versions de Apple Xcode 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 alpha device-run software-versions list

Vous recevrez une sortie semblable à la suivante :

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 alpha device-run software-versions describe xcode-16-4

Vous recevrez une sortie semblable à la suivante :

id: xcode-16-4
lifecycle:
  state: ACTIVE
name: Xcode 16.4
softwareType: XCODE
supportedIosVersions:

-   '15.0'
-   '15.1'
-   '15.2'
-   '15.4'
-   '15.7'
-   '16.0'
-   '16.1'
-   '16.2'
-   '16.3'
-   '16.5'
-   '16.6'
-   '18.0'
-   '18.3'
-   '18.4'
version: '16.4'

Maintenant que vous savez quelles versions logicielles sont disponibles, vous pouvez les utiliser dans vos exécutions de test avec l'option --xcode-version, comme suit :

gcloud alpha device-run sessions submit xctest \
  --device iphonese3-18-4 \
  --test ./IOS_TESTS.zip \
  --xcode-version=16.4

Étape 2 : Choisir les types d'appareils

À l'aide de la CLI device-run, les tests iOS peuvent être exécutés sur les appareils physiques disponibles. Pour afficher la liste complète des appareils disponibles, consultez le catalogue interactif des appareilsou exécutez la commande suivante :

gcloud alpha device-run devices list

Exemple de résultat :

ID                MAKE   NAME           MODEL        HARDWARE_TYPE  OS_VERSION  CAPACITY  AVAILABILITY  PRODUCTS
iphonese3-18-4    Apple  iPhone SE 3             iphonese3    PHYSICAL       18.4        NONE      NONE          Automation
iphonese3-26-3    Apple  iPhone SE 3             iphonese3    PHYSICAL       26.3        NONE      NONE          Automation

Consultez le catalogue des appareils pour découvrir comment filtrer cette liste. Pour cibler un appareil spécifique pour l'exécution de votre test, utilisez l'ID correspondant (par exemple, iphonese3-18-4) dans la commande d'envoi.

Étape 3 : Préparer et empaqueter votre XCTest

Avant d'exécuter vos tests, vous devez les compiler, vous assurer qu'ils sont signés, vérifier les signatures de code et empaqueter les artefacts résultants dans un fichier ZIP contenant votre configuration .xctestrun et les groupes de tests d'application.

Conseil Vous migrez depuis Firebase Test Lab ? L'exécution sur un appareil accepte le même package de test que Firebase Test Lab : le Debug-iphoneos/ répertoire et le .xctestrun fichier de Build/Products, comme décrit dans Exécuter un XCTest. Si vous disposez déjà d'un pipeline de compilation et d'empaquetage pour Firebase Test Lab, vous pouvez le réutiliser sans le modifier et transmettre le fichier .zip résultant à --test. Pour le reste de la migration, consultez la section iOS de la traduction des options et des commandes.

1. Créer vos tests pour les appareils iOS physiques

Ouvrez votre projet dans Xcode et créez votre application et vos cibles de test pour les tests :

1. Assurez-vous que la signature de code est correctement configurée dans Xcode (en spécifiant un profil de provisionnement et une identité de développeur valides) pour la cible de l'application et la cible de l'exécuteur de test.

2. Créez des tests à l'aide de Xcode (Product > Build For > Testing) ou avec xcodebuild.

   Pour un espace de travail :

   xcodebuild build-for-testing \
     -workspace YourProject.xcworkspace \
     -scheme YourScheme \
     -derivedDataPath ./build \
     -destination "generic/platform=iOS"
   

   Pour un projet autonome :

   xcodebuild build-for-testing \
     -project YourProject.xcodeproj \
     -scheme YourScheme \
     -derivedDataPath ./build \
     -destination "generic/platform=iOS"
   

Cette action génère les produits de compilation sous : ./build/Build/Products

Remarque : Vous n'avez pas besoin d'enregistrer les UDID de l'appareil d'exécution sur un appareil dans votre compte Apple Developer. La plate-forme d'appareils pour développeurs signe à nouveau votre application et vos groupes de tests avec un profil de provisionnement de laboratoire avant de les installer sur l'appareil physique. Par conséquent, un certificat de développement local et un profil de provisionnement valides sont tout ce qui est nécessaire pour effectuer les étapes de compilation et d'empaquetage.

2. Vérifier les produits et les signatures de compilation

Après la compilation, vérifiez que l'application, l'exécuteur et le fichier manifeste .xctestrun ont été générés sous ./build/Build/Products/. Si vous êtes connecté localement, vous pouvez vérifier les signatures de groupe à l'aide de codesign :

1. Vérifiez l'app bundle :

   codesign --verify --deep --verbose ./build/Build/Products/Debug-iphoneos/YourApp.app
   

   Résultat attendu : YourApp.app: valid on disk

2. Si vous exécutez un XCUITest, vérifiez également le groupe de l'exécuteur de test :

   codesign --verify --deep --verbose ./build/Build/Products/Debug-iphoneos/YourApp-Runner.app
   

   Résultat attendu : YourApp-Runner.app: valid on disk

Remarque : Un groupe YourApp-Runner.app distinct n'est produit que pour les cibles de test d'interface utilisateur (XCUITest). Les tests unitaires hébergés par l'application sont intégrés à l'application hôte et sont couverts par la vérification de YourApp.app.

3. Créer l'archive ZIP

Compressez le répertoire Debug-iphoneos et le fichier .xctestrun situés dans le dossier des produits de sortie de compilation dans une seule archive ZIP.

Attention : Le répertoire Debug-iphoneos/ et le fichier .xctestrun doivent résider directement à la racine de l'archive ZIP. Ne compressez PAS le dossier Products/ ou build/ externe.

Exécutez la commande suivante à partir du répertoire des produits de compilation :

cd ./build/Build/Products
zip -r MyTests.zip Debug-iphoneos *.xctestrun

Cette action crée le fichier MyTests.zip empaqueté, prêt à être utilisé avec l'option --test.

Étape 4 : Exécuter votre XCTest

Notez que ces options sont obligatoires :

• Appareil : spécifiez un appareil à l'aide de --device : --device iphonese3-18-4
• Test : spécifiez le fichier ZIP de test à l'aide de --test : --test ./MyTests.zip

Pour exécuter votre XCTest, utilisez la commande gcloud alpha device-run sessions submit xctest. Vous devez fournir le fichier ZIP de test (MyTests.zip) compilé à l'étape précédente.

Pour exécuter une session de test de base :

gcloud alpha device-run sessions submit xctest \
  --device iphonese3-18-4 \
  --test ./MyTests.zip

Lorsque l'exécution commence, la CLI affiche l'ID de session créé et la destination Cloud Storage où les résultats seront stockés :

Creating session [session-ee78b0ed] in location [global].
Result files will be stored at [https://console.cloud.google.com/storage/browser/BUCKET_NAME/automation/sessions/session-ee78b0ed/].

Waiting for session [session-ee78b0ed] to complete....

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

Vous pouvez suivre les exécutions actives et gérer les sessions historiques à l'aide des commandes suivantes :

• Décrire la session : interrogez la progression en direct ou les résultats finaux d'une session : gcloud alpha device-run sessions describe SESSION_ID Ajoutez --full pour afficher tous les détails, y compris les allocations d'appareils, les ID d'exécution et les chemins d'artefact Cloud Storage.
• Lister les sessions : affichez vos exécutions récentes : gcloud alpha device-run sessions list --limit=10
• Annuler la session : arrêtez une session de test en cours d'exécution : gcloud alpha device-run sessions cancel SESSION_ID
• Annuler l'opération : arrêtez une opération en attente ou active : gcloud alpha device-run operations cancel OPERATION_ID

Étape suivante

Ensuite, recherchez et analysez les journaux.