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 test XCTest per iOS utilizzando l'interfaccia a riga di comando gcloud alpha device-run e trovare i risultati nella console Google Cloud . Si presuppone che tu abbia un account e un progetto Google Cloud .

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 skill di migrazione per gli agenti AI.

Per utilizzare l'interfaccia a riga di comando device-run, devi fornire l'ID progetto Google Cloud. Consulta gcloud alpha device-run per un riepilogo dei comandi.

Prima di iniziare

Questi passaggi presuppongono che tu abbia già:

1. Creato un progetto Google Cloud .
2. Configura Developer Device Platform seguendo la guida rapida.
3. Autenticazione con gcloud nel terminale.
4. Hai esaminato la panoramica di Device Run per informazioni generali.
5. Compilato i test e creato un pacchetto 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 tramite l'interfaccia a riga di comando alle versioni di Xcode supportate con il flag --xcode-version, ad esempio: --xcode-version=xcode-16-4
• Timeout del test: limita la durata dell'esecuzione: --xctest-timeout=10m (l'intervallo valido è compreso tra 1m e 1h e il valore predefinito è 5m).
• Etichette: allega i metadati definiti dall'utente alla sessione: --labels=env=staging,owner=my-team
• Impostazioni internazionali: imposta le impostazioni internazionali del dispositivo: --locale=en-US
• Invia file al dispositivo: invia i file al container dei dati dell'app prima dell'esecuzione del test: --other-files-to-push=/tmp/data.txt=com.example.app:/Documents/data.txt
• Estrai i file dal dispositivo: estrai i file dal container di dati dell'app dopo l'esecuzione del test: --paths-to-pull=com.example.app:/Documents/output.txt
• Tentativi di ripetizione dei test instabili: imposta il numero massimo di tentativi di ripetizione dei test instabili: --flaky-test-attempts=3 (il valore predefinito è 1 tentativo).
• Bucket Cloud Storage personalizzato: specifica un bucket Cloud Storage personalizzato per gli input e gli 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 tuoi file utilizzando i relativi percorsi gs:// di Cloud Storage per risparmiare tempo di caricamento.

Esecuzioni sincrone e asincrone

Per impostazione predefinita, il comando submit è 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 su 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 l'operazione 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.

Separati 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 di 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 il relativo 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 tue esecuzioni di test con il flag --xcode-version, in questo modo:

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 l'interfaccia a riga di comando device-run, i test per 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 dei 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 submit.

Passaggio 3: Prepara e pacchettizza il tuo XCTest

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

Suggerimento: esegui la migrazione da Firebase Test Lab? Device Run accetta lo stesso pacchetto di test di Firebase Test Lab: la directory Debug-iphoneos/ e il file .xctestrun di Build/Products, come descritto in Esegui un XCTest. Se hai già una pipeline di build e pacchettizzazione 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 i target 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 il target dell'app sia per il target dell'esecutore del test.

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"
   

In questo modo vengono generati i prodotti della 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 del lab prima di installarli sul dispositivo fisico, quindi per completare i passaggi di build e pacchettizzazione sono necessari solo un certificato di sviluppo locale e un profilo di provisioning validi.

2. Verifica i prodotti e le firme della build

Dopo la creazione, verifica che l'applicazione, l'esecutore e il manifest .xctestrun siano stati generati in ./build/Build/Products/. Se la firma è stata eseguita localmente, puoi verificare le firme del bundle utilizzando codesign:

1. Verifica l'app bundle:

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

   Output previsto: YourApp.app: valid on disk

2. Se esegui un test 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: viene generato un bundle YourApp-Runner.app separato solo per i target dei test UI (XCUITest). I test delle unità ospitati dall'applicazione sono invece 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 trovano nella cartella dei prodotti di output della build in un unico file ZIP.

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

Esegui questo comando dalla directory dei prodotti di build:

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

In questo modo viene creato il pacchetto MyTests.zip pronto per essere utilizzato con il flag --test.

Passaggio 4: Esegui 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 l'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

All'inizio dell'esecuzione, l'interfaccia a riga di comando visualizza l'ID sessione creato e la destinazione 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 sullo stato di avanzamento 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, tra cui le allocazioni dei dispositivi, gli ID 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

Ora trova e analizza i log.