Developer Device Platform Device Run

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

Per utilizzare questa Google Cloud CLI, dovrai fornire l'ID Google Cloud progetto. Consulta gcloud beta device-run per un riepilogo dei comandi.

Prima di iniziare

Questi passaggi presuppongono che tu abbia già creato un Google Cloud progetto, completato i passaggi di configurazione nella piattaforma per dispositivi degli sviluppatori Guida rapida e autenticato con gcloud nel terminale.

Inoltre, dovrai avere un test di strumentazione Android pronto per l'esecuzione. Per indicazioni, consulta Creare test strumentati per guidance.

Inoltre, dovresti aver identificato gli ID dispositivo su cui vuoi eseguire i carichi di lavoro. Per istruzioni, consulta il catalogo dei dispositivi.

Suggerimento: aggiungi --help a qualsiasi comando gcloud per visualizzare informazioni dettagliate sull'utilizzo.

Esegui un test

Ora che conosci gli ID dei dispositivi disponibili per testare la tua app, puoi specificare i dispositivi utilizzando il comando gcloud beta device-run sessions submit instrumentation e il flag --device per eseguire i test di strumentazione.

Suggerimento: per visualizzare tutti i flag disponibili, esegui gcloud beta device-run sessions submit instrumentation --help.

Per eseguire il test, esegui un comando simile al seguente, ma con 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 è disponibile in un percorso di Cloud Storage, ad esempio gs://<your_project_id>/automation/sessions/session-id/. Consulta l'output del test per il link, simile a: https://console.cloud.google.com/storage/browser/your_project_id/automation/sessions/session-id/.

Configura l'esecuzione del test

Ora che hai eseguito un test, esplora alcune opzioni di configurazione:

• Per eseguire gli stessi test su più dispositivi, fornisci il flag --devicecon più ID dispositivo separati da virgole, ad esempio --device shiba-34,tokay-36, o con più flag --device, ognuno che specifica un ID dispositivo distinto (ad es. --device shiba-34 --device tokay-36).
• Facoltativamente, puoi specificare uno o più APK 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.
• Devi specificare l'APK di test con il flag --test.
• Quando specifichi un percorso locale con i flag --apps o --test, Google Cloud CLI CLI lo copia automaticamente nel bucket Cloud Storage in gs://my-project-id/automation/inputs/date_time_four_chars_suffix/ ogni volta che esegui il comando.
• Poiché il caricamento di APK di grandi dimensioni può richiedere molto tempo, puoi fare riferimento direttamente agli APK utilizzando i percorsi gs:// di Cloud Storage per risparmiare tempo di caricamento.

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

Per impostazione predefinita, il comando sessions submit instrumentation blocca i risultati della sessione, il che significa che attenderà il completamento dell'esecuzione del test e genererà risultati simili a:

Using the default Cloud Storage bucket [gs://<my-project-id>] for input and result files. Will create the bucket if it does not exist.
Uploading [app.apk].
Uploading [test.apk].

Initiated long-running operation [operation-number] to create session.
Creating session [session-id] in location [global].
Result files will be stored at [https://console.cloud.google.com/storage/browser/<my-project-id>/automation/sessions/session-id/].
Waiting for session [session-id] to complete....done.

Session [session-id] finished with result [FAILED].
JOB NAME  EXECUTION NAME  EXECUTION RESULT
job-000   all             FAILED: 2 test cases failed, 5 passed

Per eseguire il comando in modo asincrono, includi il flag --async. In questo modo, il comando può uscire immediatamente dopo aver caricato i file in Cloud Storage e stampato l'ID operazione e l'ID sessione. Puoi utilizzare il comando operations wait e l'ID operazione per attendere l'esecuzione. Si bloccherà fino al completamento del job:

gcloud beta device-run operations wait your_operation_id

Utilizza lo sharding

Per includere la piattaforma per dispositivi degli sviluppatori in un flusso di lavoro di integrazione continua e distribuzione continua (CI/CD), ti consigliamo di utilizzare lo sharding dei test. Lo sharding dei test divide un insieme di test in sottogruppi (shard) che vengono eseguiti separatamente in modo isolato. La piattaforma per dispositivi degli sviluppatori esegue automaticamente ogni shard in parallelo utilizzando più dispositivi e completa l'intero insieme di test in meno tempo.

**Attenzione:** lo sharding dei test potrebbe costare di più. Sebbene lo sharding 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.

Opzioni di sharding

Se i job hanno solo un numero ridotto di test case o il tempo di esecuzione totale di tutti i test case non è lungo, non è necessario utilizzare lo sharding. Se hai un numero elevato di test case o il tempo di esecuzione totale di tutti i test case è lungo, valuta la possibilità di utilizzare lo sharding.

La piattaforma per dispositivi degli sviluppatori supporta sia lo sharding intelligente che quello uniforme. Quando decidi come eseguire lo sharding dei test, considera le seguenti opzioni:

• Se tutti i test case richiedono un tempo simile, utilizza lo sharding uniforme dividendo tutti i test case in n shard.

• Quando il tempo di esecuzione di diversi test case varia notevolmente, utilizza lo sharding intelligente. La piattaforma per dispositivi degli sviluppatori utilizza il tempo di esecuzione dei test storici per creare shard diversi e tenta di completare tutti gli shard in una durata simile.

Nota: il numero di shard è configurabile, quindi quando la piattaforma per dispositivi degli sviluppatori esegue molti shard in parallelo, le esecuzioni dei test potrebbero essere limitate dalla disponibilità dei dispositivi. Per questo motivo, ti consigliamo di impostare il numero di dispositivi specificato nel flag --device in modo che sia minore 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 visualizzare 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, nell'output finale del comando verranno visualizzati i due job elencati separatamente:

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 intelligente, 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 come segue:

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 visualizzare un output finale che indica l'esecuzione di 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 intelligente utilizzati qui:

• --smart-sharding-max-shard-count=SMART_SHARDING_MAX_SHARD_COUNT - Specifica il numero massimo di shard da creare per lo sharding intelligente. Se non viene impostato o 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 intelligente. 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 sharding intelligente, escludendo l'estensione del file. Obbligatorio quando --sharding-option=smart. Questo file YAML si trova nel Google Cloud bucket Storage specificato da --bucket-name nella smart-sharding/ directory. Se il file non esiste, verrà creato automaticamente; in caso contrario, i contenuti verranno aggiornati al termine della sessione.

Esplora e gestisci l'esecuzione del test

Per la modalità asincrona e sincrona del comando sessions submit instrumentation, puoi utilizzare il comando sessions describe per eseguire una query sullo stato del job durante l'esecuzione o ottenere il risultato al termine:

gcloud beta device-run sessions describe <session_id>

L'output riepiloga i risultati dei test e fornisce i link ai risultati nella Google Cloud console. Ad esempio:

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

Utilizza il seguente comando 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 a:

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 di elenco sessions supporta tutte le opzioni dei flag gcloud standard. Ad esempio:

gcloud beta device-run sessions list --limit 5

Che genera risultati simili a:

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 a:

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 your_session_id

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

Se la sessione è già terminata, viene stampato solo lo stato attuale. La richiesta di annullamento per una sessione terminata non è un errore.

Passaggi successivi

Il passaggio successivo consiste nel trovare e analizzare i log.