Developer Device Platform Device Run per la strumentazione Android

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 di instrumentazione Android utilizzando l'interfaccia a riga di comandogcloud beta device-rune 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 Google Cloud CLI, devi fornire l'ID progetto Google Cloud . Consulta gcloud beta 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. Creare un test di instrumentazione per Android.

Passaggio 1: Configura l'esecuzione del test

Suggerimento: per visualizzare tutte le opzioni disponibili per i comandi submit, esegui gcloud beta device-run sessions submit instrumentation --help.

Opzioni per i test di instrumentazione Android

• Più dispositivi: per eseguire lo stesso test su più dispositivi, fornisci il flag --device con più ID dispositivo separati da virgole, ad esempio --device shiba-34,tokay-36, o con più flag --device, ognuno dei quali specifica un ID dispositivo distinto (ad esempio, --device shiba-34 --device tokay-36).
• Invia file al dispositivo: invia file aggiuntivi (come pesi del modello ML, input di test o librerie condivise .so) al dispositivo prima dell'esecuzione utilizzando --other-files-to-push=SOURCE=DEST,.... SOURCE supporta sia i percorsi locali sia i percorsi Cloud Storage (gs://...) e DEST è il percorso di destinazione sul dispositivo.
• Estrai i file dal dispositivo: estrai i file o le directory generati dal dispositivo al termine dell'esecuzione utilizzando --paths-to-pull=DEVICE_PATH,....
• Bucket Cloud Storage personalizzato: specifica il nome di un bucket Cloud Storage esistente (senza uno schema o un percorso gs://) utilizzando --bucket-name=. Se non specifichi un bucket, Google Cloud CLI utilizza o crea un bucket predefinito denominato PROJECT_ID-devicerun.
• Nuovi tentativi per test instabili: imposta il numero massimo di tentativi per job o shard per gestire l'instabilità: --flaky-test-attempts=3 (il valore predefinito è 1 tentativo).
• Ambiente e diagnostica del dispositivo: configura l'orientamento del dispositivo (--orientation=portrait o landscape), le impostazioni internazionali (--locale=en-US), la posizione GPS fittizia (--coordinates=LATITUDE,LONGITUDE), la registrazione video dello schermo (--video=always o on-failure), la raccolta di dumpsys (--dumpsys=always o on-failure) o la raccolta di bugreport (--bugreport=always o on-failure).
• Etichette: associa alla sessione etichette coppia chiave-valore definite dall'utente utilizzando --labels=KEY=VALUE,....
• App aggiuntive: facoltativamente, puoi specificare uno o più file APK, AAB o APKS da installare prima di eseguire i test utilizzando il flag --apps=path1,path2,...,path_n. L'ordine specificato è l'ordine in cui vengono installate queste app.
• Timeout del test: limita la durata dell'esecuzione: --instrumentation-timeout=10m (l'intervallo valido va da 1m a 3h e il valore predefinito è 5m).

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 beta device-run sessions submit instrumentation \
  --device shiba-35 \
  --test ./ANDROID_TESTS.apk \
  --async

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

gcloud beta 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:

gcloud beta device-run sessions submit instrumentation \
  --device shiba-34,tokay-36 \
  --test ./ANDROID_TESTS.apk

Oppure:

gcloud beta device-run sessions submit instrumentation \
  --device shiba-34 \
  --device tokay-36 \
  --test ./ANDROID_TESTS.apk

Timeout test

Limita la durata di esecuzione del test:

gcloud beta device-run sessions submit instrumentation \
  --device shiba-35 \
  --test ./ANDROID_TESTS.apk \
  --instrumentation-timeout=10m

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

Versioni software

Scopri e utilizza i pacchetti software e le versioni di AndroidX Test Orchestrator 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 beta 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 beta device-run software-versions describe androidx-test-orchestrator-1-4-1

Ricezione di un output simile al seguente:

id: androidx-test-orchestrator-1-4-1
isDefault: true
lifecycle:
  state: ACTIVE
name: AndroidX Test Orchestrator 1.4.1
softwareType: ANDROIDX_TEST_ORCHESTRATOR
version: 1.4.1

Ora che sai quali versioni software sono disponibili, puoi utilizzarle nelle tue esecuzioni di test con il flag --orchestrator-version, in questo modo:

gcloud beta device-run sessions submit instrumentation \
  --device shiba-35 \
  --test ./ANDROID_TESTS.apk \
  --orchestrator-version=1.4.1

Attiva l'agente di orchestrazione

Developer Device Platform supporta Android Test Orchestrator, che ti consente di eseguire ogni test della tua app all'interno della propria chiamata di Instrumentation.

Quando utilizzi Orchestrator:

• Evita lo stato condiviso. Ogni test viene eseguito nella propria istanza Instrumentation. Pertanto, se i test condividono lo stato dell'app, la maggior parte di questo stato condiviso viene rimossa dalla CPU o dalla memoria del dispositivo dopo ogni test. Per rimuovere tutti gli stati condivisi dalla CPU e dalla memoria del dispositivo dopo ogni test, includi l'impostazione clearPackageData in questo modo: --additional-test-options clearPackageData=true

• Isola gli arresti anomali. Se un test si arresta in modo anomalo, viene interrotta solo la sua istanza di Instrumentation. Ciò significa che gli altri test vengono comunque eseguiti e forniscono risultati completi.

Android Test Orchestrator è disattivato per impostazione predefinita in Developer Device Platform. Per attivare l'orchestratore e specificare la versione da utilizzare durante l'esecuzione del test, passa la versione selezionata al flag --orchestrator-version=ORCHESTRATOR_VERSION nel comando sessions submit instrumentation, in questo modo:

gcloud beta device-run sessions submit instrumentation \
  --device shiba-35 \
  --test ./ANDROID_TESTS.apk \
  --orchestrator-version=1.4.1

Imposta il flag su auto per utilizzare la versione dell'agente di orchestrazione predefinita del sistema.

Nota: poiché ogni test di Orchestrator esegue la propria istanza di Instrumentation, l'aumento dei tempi di esecuzione potrebbe aumentare l'utilizzo della quota o il tempo fatturato e farti superare i limiti di timeout dei dispositivi. Potresti dover aumentare di conseguenza l'impostazione del timeout della strumentazione con il flag --instrumentation-timeout.

Passaggio 2: Scegli dispositivi

Utilizzando l'interfaccia a riga di comando device-run, i test Android possono essere eseguiti su dispositivi fisici e virtuali disponibili. Per visualizzare l'elenco completo dei dispositivi disponibili, visita il catalogo dei dispositivi interattivo o esegui:

gcloud beta device-run devices list

Output di esempio:

ID        MAKE    NAME     MODEL FORM      OS_VERSION CAPACITY  AVAILABILITY  PRODUCTS
tegu-35   Google  Pixel 9a tegu  PHYSICAL  35         MEDIUM    LOW           Automation, Streaming
tokay-34  Google  Pixel 9  tokay PHYSICAL  34         HIGH      HIGH          Automation, Streaming

Consulta il Catalogo dei dispositivi per scoprire come filtrare questo elenco. Per scegliere come target un dispositivo specifico per l'esecuzione, utilizza l'ID corrispondente (ad esempio tegu-35) nel comando di invio.

Passaggio 3: Esegui il test

Invia un APK di test di instrumentazione Android.

Questi flag sono obbligatori per i test di instrumentazione Android:

• Dispositivo: specifica un dispositivo utilizzando --device: --device shiba-35
• Test: specifica l'APK di test utilizzando --test: --test /path/to/test.apk

Per eseguire il test di instrumentazione, esegui un comando sessions submit instrumentation simile al seguente, utilizzando i tuoi ID dispositivo e il percorso di test:

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

La cartella del report dei risultati del job si trova in un percorso di Cloud Storage, ad esempio gs://BUCKET_NAME/automation/sessions/SESSION_ID/. Consulta l'output comando per il link, simile a: https://console.cloud.google.com/storage/browser/BUCKET_NAME/automation/sessions/SESSION_ID/.

Passaggio 4: Utilizza lo sharding

Per includere i test di instrumentazione di Developer Device Platform in un workflow di integrazione continua e distribuzione continua (CI/CD), ti consigliamo di eseguire lo sharding dei test. Il partizionamento dei test suddivide un insieme di test di instrumentazione in sottogruppi (partizioni) che vengono eseguiti separatamente in modo isolato. Developer Device Platform esegue automaticamente ogni shard in parallelo utilizzando più dispositivi e completa l'intero set di test in meno tempo.

Attenzione: i test di sharding potrebbero costare di più. Sebbene il partizionamento dei test riduca il tempo necessario per l'esecuzione di tutti i test, l'overhead dell'avvio dell'app su ogni shard potrebbe aumentare i tempi dei singoli dispositivi.

Passaggio 4.1. Scelta dell'opzione di sharding

Se i tuoi job hanno solo un numero ridotto di scenari di test o il tempo di esecuzione totale di tutti gli scenari di test non è lungo, non è necessario utilizzare lo sharding. Se hai un numero elevato di scenari di test o se il tempo di esecuzione totale di tutti gli scenari di test è lungo, valuta l'utilizzo dello sharding.

Developer Device Platform supporta lo sharding smart e uniforme. Quando decidi come eseguire lo sharding dei test, considera le seguenti opzioni:

• Se tutti gli scenari di test richiedono un tempo simile, utilizza lo sharding uniforme dividendo tutti gli scenari di test in n shard.

• Quando il tempo di esecuzione dei diversi scenari di test varia notevolmente, utilizza lo sharding smart. Developer Device Platform utilizza il tempo di esecuzione dei test storici per creare shard diversi e tenta di completare tutti gli shard in un tempo simile.

Nota: il numero di shard è configurabile, quindi quando Developer Device Platform esegue molti shard in parallelo, le esecuzioni dei test potrebbero essere limitate dalla disponibilità dei dispositivi. Per questo motivo, ti consigliamo di specificare nel flag --device un numero di dispositivi inferiore o uguale al numero di shard.

Sharding uniforme

Per eseguire lo sharding dei test con lo sharding uniforme, includi i flag --sharding-option=uniform e --uniform-sharding-count= nel comando sessions submit instrumentation, come segue:

gcloud beta device-run sessions submit instrumentation \
    --test path/to/test.apk \
 --device shiba-34,tokay-36 \
    --sharding-option=uniform \
    --uniform-sharding-count=2

Dovresti vedere un output che indica Job status: 2 running. Il servizio crea due job, uno per ogni dispositivo. Poiché gli input di entrambi i job sono identici, il servizio centralizza la convalida, eseguendola una sola volta.

Al termine, i due job verranno visualizzati separatamente nell'output finale del comando:

JOB NAME  EXECUTION NAME  EXECUTION RESULT
job-000   execution-000   PASSED
job-001   execution-000   PASSED

Sharding intelligente

Per eseguire lo sharding dei test con lo sharding smart, includi i flag --sharding-option=smart, --smart-sharding-max-shard-count=, --smart-sharding-target-duration= (in minuti o 1h) e --smart-sharding-record-name= nel comando sessions submit instrumentation, in questo modo:

gcloud beta device-run sessions submit instrumentation \
    --test path/to/test.apk \
    --device shiba-34,shiba-35,tokay-36 \
    --sharding-option=smart \
    --smart-sharding-max-shard-count=3 \
    --smart-sharding-target-duration=5m \
    --smart-sharding-record-name=test.yaml

Dovresti vedere l'output finale che indica che sono stati eseguiti tre job:

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

Ecco un riepilogo dei flag di sharding smart utilizzati qui:

• --smart-sharding-max-shard-count=SMART_SHARDING_MAX_SHARD_COUNT: specifica il numero massimo di shard da creare per lo sharding smart. Se non viene impostato o se viene impostato su 0, vengono utilizzati i limiti massimi definiti dal sistema. L'intervallo valido è compreso tra 0 e 20 per i dispositivi fisici e tra 0 e 200 per i dispositivi virtuali.

• --smart-sharding-target-duration=SMART_SHARDING_TARGET_DURATION: specifica il tempo di esecuzione target (ad es. 2m, 10m, 1h) per shard per lo sharding smart. L'intervallo valido è compreso tra 2m e 1h. Obbligatorio quando --sharding-option=smart.

• --smart-sharding-record-name=SMART_SHARDING_RECORD_NAME: specifica il nome del file di record di smart sharding, esclusa l'estensione del file. Obbligatorio quando --sharding-option=smart. Questo file YAML si trova nel bucket Cloud Storage Google Cloudspecificato da --bucket-name nella directory smart-sharding/. Se il file non esiste, verrà creato automaticamente; in caso contrario, i suoi contenuti verranno aggiornati al termine della sessione.

Passaggio 5: Esplora e gestisci l'esecuzione del test

Sia per la modalità asincrona che per quella sincrona del comando sessions submit instrumentation, puoi utilizzare il comando sessions describe per eseguire query sullo stato del job durante l'esecuzione o ottenere il risultato dopo il completamento:

gcloud beta device-run sessions describe SESSION_ID

L'output riassume i risultati del test e i link ai risultati nella console Google Cloud . Ad esempio:

Session SESSION_ID finished with result [FAILED].
Result files are stored at [https://console.cloud.google.com/storage/browser/BUCKET_NAME/automation/sessions/SESSION_ID/].
JOB NAME  EXECUTION NAME  EXECUTION RESULT
job-000   all             FAILED: 2 test cases failed, 5 passed

Utilizza il comando seguente per elencare tutte le sessioni in esecuzione e completate:

gcloud beta device-run sessions list

Ricevi un output contenente l'elenco delle sessioni nel tuo progetto, simile al seguente:

SESSION_ID                                    START_TIME                STATE
session-4825e153                              2026-07-28T16:38:43.155Z  DONE
session-813ca602                              2026-07-28T22:40:32.415Z  DONE
session-67cd0570                              2026-07-16T08:25:55.474Z  DONE
session-17cc299c                              2026-07-14T14:31:33.649Z  DONE
session-911d0763                              2026-07-09T00:39:02.051Z  DONE
session-4e943fea                              2026-07-15T23:08:32.252Z  DONE
session-0132e458                              2026-08-20T18:33:19.751Z  DONE
session-1077f07b                              2026-07-28T22:35:43.848Z  DONE
session-71b054c6                              2026-07-15T01:15:41.643Z  DONE
session-4f8b2e45                              2026-08-06T23:11:56.161Z  DONE

Il comando sessions list supporta tutte le opzioni standard dei flag di Google Cloud CLI. Ad esempio:

gcloud beta device-run sessions list --limit 5

Il risultato è simile al seguente:

SESSION_ID                            START_TIME                STATE
session-4825e153                      2026-07-28T16:38:43.155Z  DONE
session-813ca602                      2026-07-28T22:40:32.415Z  DONE
93ec2df2-d5bf-4c36-b7f7-c2a4fb0dc3ce  2026-07-03T05:10:58.015Z  DONE
session-67cd0570                      2026-07-16T08:25:55.474Z  DONE
session-17cc299c                      2026-07-14T14:31:33.649Z  DONE

In alternativa, per trovare tutte le sessioni in esecuzione, esegui:

gcloud beta device-run sessions list --filter RUNNING

Supponendo che tu abbia sessioni in esecuzione, vedrai risultati simili ai seguenti:

SESSION_ID        START_TIME  STATE
session-d7ff8b81              RUNNING

In caso contrario, riceverai Listed 0 items.

Per annullare una sessione in esecuzione, esegui questo comando con l'ID sessione:

gcloud beta device-run sessions cancel SESSION_ID

Il comando restituisce immediatamente un risultato, poiché la sessione è solo contrassegnata per l'annullamento. L'annullamento avviene in modo asincrono nel backend.

Se la sessione è già terminata, viene stampato solo lo stato attuale. Richiedere l'annullamento di una sessione terminata non è un errore.

Passaggi successivi

Ora esegui un file eseguibile Android o trova e analizza i log.