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 instrumentazione Android o un eseguibile Android autonomo Android utilizzando l'interfaccia a riga di comando gcloud beta device-run e come trovare i risultati in 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 skill di migrazione per gli agenti AI.

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

Prima di iniziare

Questi passaggi presuppongono che tu abbia già:

1. Creatoun Google Cloud progetto.
2. Configurato Developer Device Platform seguendo la guida rapida.
3. Eseguito l'autenticazione con gcloud nel terminale.
4. Esaminato la panoramica di Device Run per informazioni generali.
5. Creato un test di instrumentazione per Android o preparato un eseguibile Android autonomo (ad esempio un file binario C++ compilato, un runner di benchmark o uno script shell).

Passaggio 1: configura l'esecuzione del test o dell'eseguibile

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

Ora che hai eseguito una sessione, esplora alcune opzioni di configurazione:

Opzioni per test di instrumentazione ed eseguibili

• Più dispositivi: per eseguire lo stesso test o eseguibile 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).
• Esegui il push dei file sul dispositivo: esegui il push di file aggiuntivi (come i pesi del modello ML, gli input di test o le librerie condivise .so) sul dispositivo prima dell'esecuzione utilizzando --other-files-to-push=SOURCE=DEST,.... SOURCE supporta sia i percorsi locali sia i percorsi Cloud Storage (gs://...), mentre DEST è il percorso di destinazione sul dispositivo.
• Esegui il pull dei file dal dispositivo: esegui il pull dei file o delle 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 schema o 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 di 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 simulata (--coordinates=LATITUDE,LONGITUDE), la registrazione video dello schermo (--video=always o on-failure), la raccolta dumpsys (--dumpsys=always o on-failure) o la raccolta bugreport (--bugreport=always o on-failure).
• Etichette: associa etichette coppia chiave-valore definite dall'utente alla sessione utilizzando --labels=KEY=VALUE,....

Opzioni per i test di instrumentazione

• App aggiuntive: facoltativamente, puoi specificare uno o più file APK, AAB o APKS da installare prima di eseguire i test utilizzando il --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 è compreso tra 1m e 3h e il valore predefinito è 5m).

Opzioni per gli eseguibili Android

• Argomenti eseguibili: passa gli argomenti della riga di comando all'eseguibile utilizzando --executable-args=ARG,... come elenco separato da virgole o ripetendo il flag. Ogni elemento diventa un argomento, quindi riscrivi le righe di comando separate da spazi in formato separato da virgole (ad esempio, --executable-args="--input=a.file,--threads=4"). Per passare un argomento che contiene una virgola, anteponi al valore ^SEP^ per specificare un separatore diverso (ad esempio, --executable-args="^;^--shape=1,224,224,3;--threads=4").
• Variabili di ambiente: imposta le variabili di ambiente per il processo eseguibile sul dispositivo utilizzando --executable-env-vars=KEY=VALUE,... (ad esempio, --executable-env-vars=LD_LIBRARY_PATH=/data/local/tmp/lib).
• Timeout eseguibile: limita la durata dell'esecuzione dell'eseguibile: --executable-timeout=10m (l'intervallo valido è compreso tra 1m e 3h e il valore predefinito è 5m, escluso il tempo di preparazione e pulizia del dispositivo).

Esecuzioni sincrone e asincrone

Per impostazione predefinita, il comando submit è bloccante (sincrono). Attenderà il completamento del test o dell'eseguibile 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:

Test di instrumentazione Android

Per un :

gcloud beta device-run sessions submit instrumentation \
  --device shiba-35 \
  --test ./ANDROID_TESTS.apk \
  --async

Eseguibile Android

gcloud beta device-run sessions submit android-executable \
  --device shiba-35 \
  --executable ./MY_EXECUTABLE \
  --async

Viene restituito immediatamente un ID sessione. Puoi quindi attendere 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 o eseguibile 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.

Test di instrumentazione Android

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

Eseguibile Android

gcloud beta device-run sessions submit android-executable \
  --device shiba-34,tokay-36 \
  --executable ./MY_EXECUTABLE

Oppure:

gcloud beta device-run sessions submit android-executable \
  --device shiba-34 \
  --device tokay-36 \
  --executable ./MY_EXECUTABLE

Timeout di test ed eseguibili

Limita la durata dell'esecuzione del test o dell'eseguibile:

Test di instrumentazione Android

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

Eseguibile Android

gcloud beta device-run sessions submit android-executable \
  --device shiba-35 \
  --executable ./MY_EXECUTABLE \
  --executable-timeout=10m

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

Versioni software

Scopri e utilizza i pacchetti software e le versioni disponibili di AndroidX Test Orchestrator ed esamina i relativi cicli di vita, le versioni supportate e i metadati prima di configurare le esecuzioni di test.

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

gcloud beta device-run software-versions list

Ricevi 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

Ricevi 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 esecuzioni di test con il flag --orchestrator-version, come segue:

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

Per ulteriori informazioni, consulta la sezione Attivare Orchestrator.

Attivare Orchestrator

Per i test di instrumentazione, Developer Device Platform supporta Android Test Orchestrator, che ti consente di eseguire ogni test della tua app nella propria chiamata di Instrumentation.

Quando utilizzi Orchestrator:

• Evita lo stato condiviso. Ogni test viene eseguito nella propria istanza di 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 tutto lo stato condiviso dalla CPU e dalla memoria del dispositivo dopo ogni test, includi l'impostazione clearPackageData come segue: --additional-test-options clearPackageData=true

• Isola gli arresti anomali. Se un test si arresta in modo anomalo, viene arrestata solo la relativa 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 Orchestrator e specificare la versione da utilizzare durante l'esecuzione del test, passa la versione selezionata al --orchestrator-version=ORCHESTRATOR_VERSION flag nel tuo sessions submit instrumentation comando, come segue:

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 di Orchestrator 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 causare il superamento dei limiti di timeout dei dispositivi. Potresti dover aumentare di conseguenza l'impostazione del timeout di instrumentazione con il flag --instrumentation-timeout.

Passaggio 2: scegli i dispositivi

Utilizzando l'interfaccia a riga di comando device-run, i test e gli eseguibili 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 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 submit.

Passaggio 3: esegui il test o l'eseguibile

Puoi inviare un APK di test di instrumentazione Android o un eseguibile Android autonomo.

Esegui un test di instrumentazione

Tieni presente che 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 sessions submit instrumentation comando 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

Esegui un eseguibile Android

Per eseguire un eseguibile autonomo (ad esempio un file binario C++ compilato, un runner di benchmark di machine learning sul dispositivo come LiteRT o uno script shell) direttamente su un dispositivo Android senza impacchettarlo in un APK, utilizza il sessions submit android-executablecomando.

Tieni presente che questi flag sono obbligatori per gli eseguibili Android:

• Dispositivo: specifica un dispositivo utilizzando --device: --device shiba-35
• Eseguibile: specifica il percorso locale o di Cloud Storage dell'eseguibile utilizzando --executable: --executable /path/to/my_executable

Per eseguire l'eseguibile, esegui un comando simile al seguente, utilizzando i tuoi ID dispositivo e il percorso dell'eseguibile:

gcloud beta device-run sessions submit android-executable \
  --device shiba-34 \
  --executable /path/to/my_executable \
  --executable-args="--input=/data/local/tmp/file.name,--threads=4" \
  --other-files-to-push=/path/to/model.tflite=/data/local/tmp/model.tflite \
  --paths-to-pull=/data/local/tmp/output

La cartella dei report dei risultati del job è disponibile in un percorso Cloud Storage come 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 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 di instrumentazione 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 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, il sovraccarico dell'avvio dell'app su ogni shard potrebbe aumentare i tempi dei singoli dispositivi.

Passaggio 4.1: scegli l'opzione di sharding

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

Developer Device Platform supporta lo sharding intelligente e uniforme. Quando decidi come eseguire lo sharding dei test, prendi in considerazione le seguenti opzioni:

• Se tutti gli scenari di test richiedono una quantità di 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. Developer Device Platform 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 Developer Device Platform esegue molti shard in parallelo, le esecuzioni di test potrebbero essere limitate dalla disponibilità dei dispositivi. Per questo motivo, ti consigliamo che il numero di dispositivi specificato nel flag --device 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 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, vedrai i due job elencati 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 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 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 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 relativi contenuti verranno aggiornati al termine della sessione.

Passaggio 5: esplora e gestisci l'esecuzione del test

Per la modalità asincrona e sincrona dei sessions submit instrumentation e sessions submit android-executable comandi, puoi utilizzare il sessions describe comando 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 in Google Cloud console. 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 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:

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 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 di una sessione terminata non è un errore.

Passaggi successivi

Il passaggio successivo consiste nel trovare e analizzare i log.