Developer Device Platform Device Run per iOS

Anteprima

Questo prodotto o funzionalità sono soggetti ai "Termini dell'offerta pre-GA" nella sezione dei Termini di servizio generali dei Termini specifici dei servizi. I prodotti e le funzionalità pre-GA sono disponibili "così come sono" e potrebbero avere un supporto limitato. Per ulteriori informazioni, consulta le descrizioni della fase di lancio.

Questa guida descrive come eseguire un XCTest iOS utilizzando la gcloud alpha device-run CLI e trovare i risultati nella Google Cloud console. Si presuppone che tu abbia un Google Cloud account e un progetto.

Se stai eseguendo la migrazione da Firebase Test Lab a Developer Device Platform, consulta la nostra guida alla migrazione, la traduzione di comandi e flag e la competenza di migrazione per gli agenti AI.

Per utilizzare la CLI device-run, dovrai fornire il tuo Google Cloud ID progetto. Per un riepilogo dei comandi, consulta gcloud alpha device-run.

Prima di iniziare

Questi passaggi presuppongono che tu abbia già:

1. Creato un Google Cloud progetto.
2. Configurato Developer Device Platform seguendo la guida rapida.
3. Eseguito l'autenticazione con gcloud nel terminale.
4. Consultato la panoramica di Device Run per informazioni generali.
5. Compilato i test e li hai inseriti in un file ZIP.

Passaggio 1: configura l'esecuzione del test

Suggerimento: Per visualizzare tutte le opzioni disponibili per il comando submit xctest, esegui gcloud alpha device-run sessions submit xctest --help.

Puoi personalizzare l'esecuzione del test utilizzando i seguenti flag facoltativi (anche se è richiesta almeno un'istanza del flag --device):

• Più dispositivi: specifica il flag --device più volte per eseguire lo stesso test su più dispositivi contemporaneamente: --device iphonese3-18-4 --device iphonese3-26-3 o --device iphonese3-18-4,iphonese3-26-3
• App aggiuntive: installa uno o più pacchetti .ipa aggiuntivi prima di avviare il test utilizzando --additional-apps: --additional-apps=/path/to/AdditionalApp.ipa
• File .xctestrun personalizzato: passa un file di configurazione personalizzato con --xctestrun-file: --xctestrun-file=/path/to/CustomTests.xctestrun
• Versioni di Apple Xcode: accedi direttamente alle versioni di Xcode supportate dalla CLI con il flag --xcode-version, ad esempio: --xcode-version=xcode-16-4
• Timeout test: limita la durata dell'esecuzione: --xctest-timeout=10m (l'intervallo valido è compreso tra 1m e 1h e il valore predefinito è 5m).
• Etichette: associa metadati definiti dall'utente alla sessione: --labels=env=staging,owner=my-team
• Località: imposta le impostazioni internazionali del dispositivo: --locale=en-US
• Trasferisci file sul dispositivo: trasferisci i file nel container dei dati dell'app prima dell'esecuzione del test execution: --other-files-to-push=/tmp/data.txt=com.example.app:/Documents/data.txt
• Estrai file dal dispositivo: estrai i file dal container dei dati dell'app dopo l'esecuzione del test: --paths-to-pull=com.example.app:/Documents/output.txt
• Nuovi tentativi di test instabili: imposta il numero massimo di tentativi per eseguire di nuovo i test instabili: --flaky-test-attempts=3 (il valore predefinito è 1 tentativo).
• Bucket Cloud Storage personalizzato: specifica un bucket Cloud Storage personalizzato per input e output: --bucket-name=my-custom-bucket (il valore predefinito è PROJECT_ID-devicerun).
• Poiché il caricamento di file ZIP o IPA di grandi dimensioni può richiedere molto tempo, puoi fare riferimento direttamente ai file utilizzando i percorsi gs:// di Cloud Storage per risparmiare tempo di caricamento.

Esecuzioni sincrone e asincrone

Per impostazione predefinita, il comando di invio è bloccante (sincrono). Attenderà il completamento del test e stamperà una tabella di riepilogo dei risultati.

Per inviare la sessione e tornare immediatamente dopo aver caricato i file in Cloud Storage, aggiungi il flag --async:

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

Viene restituito immediatamente un ID sessione. Puoi quindi attendere utilizzando il comando sessions wait:

gcloud alpha device-run sessions wait SESSION_ID

Il comando verrà bloccato fino al completamento del job.

Più dispositivi

Per eseguire lo stesso test su più dispositivi, fornisci il flag --device con più ID dispositivo separati da virgole o con più flag --device, ognuno dei quali specifica un ID dispositivo distinto.

Separato da virgole

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

Più flag

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

Timeout test

Limita la durata dell'esecuzione del test:

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

L'intervallo valido è compreso tra 1m e 1h e il valore predefinito è 5m.

Versioni software

Scopri e utilizza i pacchetti software e le versioni di Apple Xcode disponibili e ispeziona i relativi cicli di vita, le versioni supportate e i metadati prima di configurare le esecuzioni dei test.

Innanzitutto, elenca tutti i pacchetti software disponibili e le relative versioni:

gcloud alpha device-run software-versions list

Ricezione di un output simile al seguente:

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

Quindi descrivi un pacchetto specifico utilizzando l'ID risorsa esatto dall'elenco:

gcloud alpha device-run software-versions describe xcode-16-4

Ricezione di un output simile al seguente:

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'

Ora che sai quali versioni software sono disponibili, puoi utilizzarle nelle esecuzioni dei test con il flag --xcode-version, come segue:

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

Passaggio 2: scegli i tipi di dispositivo

Utilizzando la CLI device-run, i test iOS possono essere eseguiti sui dispositivi fisici disponibili. Per visualizzare l'elenco completo dei dispositivi disponibili, visita il catalogo dei dispositivi interattivo o esegui:

gcloud alpha device-run devices list

Output di esempio:

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

Consulta il Catalogo dispositivi per scoprire come filtrare questo elenco. Per scegliere come target un dispositivo specifico per l'esecuzione del test, utilizza l'ID corrispondente (ad es. iphonese3-18-4) nel comando di invio.

Passaggio 3: prepara e impacchetta il tuo XCTest

Prima di eseguire i test, devi compilarli, assicurarti che siano firmati, verificare le firme del codice e inserire gli artefatti risultanti in un file ZIP contenente la configurazione .xctestrun e i bundle di test dell'applicazione.

Suggerimento: stai eseguendo la migrazione da Firebase Test Lab? Device Run accetta lo stesso pacchetto di test di Firebase Test Lab: la directory Debug-iphoneos/ e il .xctestrun file da Build/Products, come descritto in Eseguire un XCTest. Se hai già una pipeline di creazione e packaging per Firebase Test Lab, puoi riutilizzarla senza modifiche e passare il file .zip risultante a --test. Per il resto della migrazione, consulta la sezione iOS di Traduzione di flag e comandi.

1. Crea i test per i dispositivi iOS fisici

Apri il progetto in Xcode e crea l'app e le destinazioni di test per i test:

1. Assicurati che la firma del codice sia configurata correttamente in Xcode (specificando un profilo di provisioning e un'identità sviluppatore validi) sia per la destinazione dell'app sia per la destinazione del test runner.

2. Crea per i test utilizzando Xcode (Product > Build For > Testing) o con xcodebuild.

   Per uno spazio di lavoro:

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

   Per un progetto autonomo:

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

Vengono generati i prodotti di build in: ./build/Build/Products

Nota: non è necessario registrare gli UDID dei dispositivi Device Run nel tuo account sviluppatore Apple. Developer Device Platform firma nuovamente l'applicazione e i bundle di test con un profilo di provisioning di laboratorio prima di installarli sul dispositivo fisico, quindi per completare i passaggi di creazione e packaging sono necessari solo un certificato di sviluppo locale e un profilo di provisioning validi.

2. Verifica i prodotti e le firme di build

Dopo la creazione, verifica che l'applicazione, il runner e il manifest .xctestrun siano stati generati in ./build/Build/Products/. Se hai eseguito la firma in locale, puoi verificare le firme dei bundle utilizzando codesign:

1. Verifica il bundle dell'app:

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

   Output previsto: YourApp.app: valid on disk

2. Se esegui un XCUITest, verifica anche il bundle del test runner:

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

   Output previsto: YourApp-Runner.app: valid on disk

Nota: un bundle separato YourApp-Runner.app viene prodotto solo per le destinazioni di test dell'interfaccia utente (XCUITest). I test delle unità ospitati dall'applicazione sono incorporati nell'app host e sono coperti dalla verifica di YourApp.app.

3. Crea il file ZIP

Comprimi sia la directory Debug-iphoneos sia il file .xctestrun che si trova nella cartella dei prodotti di output della build in un unico file ZIP.

Attenzione :la directory Debug-iphoneos/ e il file .xctestrun devono risiedere direttamente nella directory root del file ZIP. NON comprimere la cartella Products/ o build/ esterna.

Esegui il comando seguente dalla directory dei prodotti di build:

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

Viene creato il file MyTests.zip impacchettato, pronto per essere utilizzato con il flag --test.

Passaggio 4: esegui il tuo XCTest

Tieni presente che questi flag sono obbligatori:

• Dispositivo: specifica un dispositivo utilizzando --device: --device iphonese3-18-4
• Test: specifica il file ZIP di test utilizzando --test: --test ./MyTests.zip

Per eseguire il tuo XCTest, utilizza il comando gcloud alpha device-run sessions submit xctest. Devi fornire il file ZIP di test (MyTests.zip) compilato nel passaggio precedente.

Per eseguire una sessione di test di base:

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

Quando inizia l'esecuzione, la CLI visualizza l'ID sessione creato e la destinazione di Cloud Storage in cui verranno archiviati i risultati:

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....

Passaggio 5: esplora e gestisci l'esecuzione del test

Puoi monitorare le esecuzioni attive e gestire le sessioni storiche utilizzando questi comandi:

• Descrivi sessione: esegui una query sui progressi in tempo reale o sui risultati finali di una sessione: gcloud alpha device-run sessions describe SESSION_ID Aggiungi --full per visualizzare i dettagli completi, inclusi le allocazioni dei dispositivi, gli ID di esecuzione e i percorsi degli artefatti di Cloud Storage.
• Elenca sessioni: visualizza le esecuzioni recenti: gcloud alpha device-run sessions list --limit=10
• Annulla sessione: interrompi una sessione di test in esecuzione: gcloud alpha device-run sessions cancel SESSION_ID
• Annulla operazione: interrompi un'operazione in attesa o attiva: gcloud alpha device-run operations cancel OPERATION_ID

Passaggi successivi

Il passaggio successivo consiste nel trovare e analizzare i log.