Developer Device Platform Device Run per 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 strumentazione Android utilizzando la CLI gcloud beta device-run e trovare i risultati nella console Google Cloud . Presuppone che tu abbia un account e un progetto Google Cloud .

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

Prima di iniziare

Questi passaggi presuppongono che tu abbia già:

1. Creazione di un progetto Google Cloud .
2. Configura la piattaforma per dispositivi per sviluppatori seguendo la Guida rapida.
3. Autenticato con gcloud nel terminale.
4. Ho esaminato la panoramica di Device Run per informazioni generali.
5. È stato creato un test strumentato per Android.

Passaggio 1: Scegli dispositivi

Utilizzando la CLI 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 interattivo dei dispositivi 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 del test, utilizza il relativo ID (ad es. tegu-35) nel comando di invio.

Passaggio 2: Esegui il test di strumentazione

Tieni presente che questi flag sono obbligatori per i test 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, emetti un comando simile al seguente, ma con i tuoi ID dispositivo e il percorso del 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 Cloud Storage come gs://BUCKET_NAME/automation/sessions/SESSION_ID/. Visualizza l'output del test per il link, simile a: https://console.cloud.google.com/storage/browser/BUCKET_NAME/automation/sessions/SESSION_ID/.

Passaggio 3: Configurare l'esecuzione test

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

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

• Più dispositivi: per eseguire gli stessi 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 che specifica un ID dispositivo distinto (ad es. --device shiba-34 --device tokay-36).
• App aggiuntive: 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.
• Timeout test: limita la durata dell'esecuzione: --instrumentation-timeout=10m (l'intervallo valido è compreso tra 1m e 1h e il valore predefinito è 5m).
• Bucket Cloud Storage personalizzato: se non specifichi un bucket Cloud Storage utilizzando il flag --bucket-name=, Google Cloud CLI utilizzerà un bucket predefinito denominato PROJECT_ID-devicerun.
• 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).

Passaggio 4: Utilizzare lo sharding

Per includere la piattaforma di dispositivi per sviluppatori in un flusso di lavoro di integrazione continua e distribuzione continua (CI/CD), devi prendere in considerazione la suddivisione dei test. La suddivisione dei test divide un insieme di test in sottogruppi (shard) che vengono eseguiti separatamente in isolamento. 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 lo sharding dei test riduca il tempo necessario per l'esecuzione di tutti i test, il sovraccarico dell'avvio dell'app su ogni shard potrebbe aumentare i tempi dei singoli dispositivi.

Passaggio 4.1. Scegliere l'opzione di partizionamento

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 il tempo di esecuzione totale di tutti gli scenari di test è lungo, valuta la possibilità di utilizzare lo sharding.

La piattaforma per dispositivi per sviluppatori supporta lo sharding intelligente e uniforme. Quando decidi come dividere i 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 di diversi scenari di test varia notevolmente, utilizza lo sharding intelligente. La piattaforma di dispositivi per sviluppatori utilizza il tempo di esecuzione dei test storici per creare diversi shard e tenta di completare tutti gli shard in una durata simile.

Nota: il numero di shard è configurabile, quindi quando la piattaforma per dispositivi per sviluppatori esegue molti shard in parallelo, l'esecuzione dei test potrebbe essere limitata dalla disponibilità di dispositivi. Per questo motivo, consigliamo che il numero di dispositivi specificato nel flag --device sia inferiore o uguale al numero di shard.

Partizionamento orizzontale uniforme

Per suddividere i test in shard con la suddivisione uniforme, includi i flag --sharding-option=uniform e --uniform-sharding-count= nel comando sessions submit instrumentation nel seguente modo:

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 elencati separatamente nell'output finale del comando:

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

Smart sharding

Per suddividere i test in shard con la suddivisione intelligente, includi i flag --sharding-option=smart, --smart-sharding-max-shard-count=, --smart-sharding-target-duration= (in minuti o 1 ora) e --smart-sharding-record-name= nel comando sessions submit instrumentation nel seguente 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 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 partizionamento 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 impostato o 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. 2 m, 10 m, 1 ora) per shard per lo sharding intelligente. L'intervallo valido è compreso tra 2 minuti e 1 ora. Obbligatorio quando --sharding-option=smart.

• --smart-sharding-record-name=SMART_SHARDING_RECORD_NAME: specifica il nome del file di record di smart sharding, escludendo l'estensione del file. Obbligatorio quando --sharding-option=smart. Questo file YAML si trova nel Google Cloudbucket Storage specificato 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: Esplorare e gestire l'esecuzione del test

Per la modalità asincrona e 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 riepiloga i risultati del test e rimanda 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 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 questo:

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 standard di Google Cloud CLI. Ad esempio:

gcloud beta device-run sessions list --limit 5

che restituisce 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 questi:

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 viene restituito immediatamente, poiché la sessione viene 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

Poi, trova e analizza i log.