Sharding intelligente in Device Run di Developer Device Platform

Lo sharding smart in Device Run di Developer Device Platform distribuisce i test di instrumentazione Android e gli XCTest iOS su shard paralleli utilizzando i tempi di esecuzione dei test storici archiviati in Cloud Storage. A differenza dello sharding uniforme, che divide gli scenari di test in base al conteggio indipendentemente dalla durata di ogni test, lo sharding intelligente bilancia gli shard in base alla durata prevista, in modo che gli shard paralleli terminino all'incirca nello stesso momento target.

Questo documento spiega come l'algoritmo di sharding intelligente calcola il numero di shard e assegna i test, descrive lo schema del record di temporizzazione YAML archiviato nel tuo bucket Cloud Storage e risponde alle domande comuni sull'overhead di Android Test Orchestrator e sulla finestra dei dati di 30 giorni. Per le istruzioni della riga di comando che utilizzano Google Cloud CLI, consulta le istruzioni per la strumentazione Android e iOS XCTest.

Come funziona l'algoritmo di sharding intelligente

Lo sharding non equivale al numero di test che possono essere eseguiti contemporaneamente. È possibile che i dispositivi disponibili siano inferiori al limite di shard al momento della richiesta. Il numero effettivo di dispositivi contemporanei che è possibile assegnare a un utente potrebbe essere inferiore al numero di shard specificato.

Quando invii una sessione con --sharding-option=smart in gcloud CLI o configuri smartSharding nell'API REST, Developer Device Platform esegue un workflow in sei fasi per la creazione della sessione, l'esecuzione del test e il completamento:

  1. Leggi i dati storici relativi alle tempistiche e abbinali al contesto del dispositivo. Prima di pianificare gli shard, l'agente di servizio Device Run legge il file YAML di sharding smart da Cloud Storage. Cerca nell'elenco records un shardingContext che corrisponda a deviceModel e osVersion del job di destinazione (senza distinzione tra maiuscole e minuscole). Se non esiste una corrispondenza esatta per la combinazione di dispositivo e sistema operativo, Developer Device Platform torna alla prima voce records disponibile nel file. Se il file YAML non esiste ancora, la sessione procede come un avvio a freddo con una cronologia delle tempistiche vuota.
  2. Filtra i campioni in base alla finestra temporale di 30 giorni e calcola le durate previste. Per il record di contesto selezionato, Developer Device Platform conserva solo i campioni di tempo il cui recordTime rientra negli ultimi 30 giorni e calcola la durata media aritmetica per ogni scenario di test. Se Android Test Orchestrator è abilitato con --orchestrator-version, Developer Device Platform calcola anche la media di 30 giorni dei campioni di overhead ANDROID_TEST_ORCHESTRATOR e aggiunge questo overhead medio alla durata prevista di ogni scenario di test.
  3. Scopri i test eseguibili e assegna stime di riserva. Sull'host worker, Developer Device Platform esamina staticamente il pacchetto di test, leggendo i file DEX nell'APK di test su Android o i simboli .xctest e i filtri .xctestrun compilati su iOS, applica eventuali filtri --test-targets ed esclude i test ignorati o soppressi (come @Ignore o @Suppress). Ogni unità di test eseguibile riceve una durata prevista in base a tre livelli:
    • Scenario di test registrato: utilizza la durata media storica di 30 giorni (più l'overhead medio dell'orchestratore quando Android Test Orchestrator è abilitato). Su Android, le classi JUnit parametrizzate (ad esempio le classi che utilizzano @RunWith(Parameterized.class), JUnitParamsRunner o TestParameterInjector) vengono pianificate come una singola unità a livello di classe la cui durata prevista è la somma di tutte le durate dei metodi registrate per quella classe.
    • Scenario di test non registrato in una suite esistente: utilizza la durata media prevista di tutti gli scenari di test registrati diversi da zero nel record corrispondente.
    • Avvio a freddo (nessuna cronologia registrata): utilizza una stima predefinita di 30 secondi per unità di test.
  4. Calcola il numero di shard. Developer Device Platform somma le durate previste di tutte le unità di test eseguibili e le divide per il valore --smart-sharding-target-duration configurato (valido da 2m a 1h), arrotondando per eccesso allo shard intero più vicino:

    optimal_shards = max(1, ceil(total_expected_duration / target_duration))
    

    Successivamente, Developer Device Platform imposta il numero finale di shard tra 1 e il più basso dei seguenti limiti:

    • Il numero totale di unità di test eseguibili (per evitare shard vuoti).
    • Il valore di --smart-sharding-max-shard-count, se impostato su un valore superiore a 0.
    • Il limite della piattaforma (20 shard per i dispositivi fisici o 200 shard per i dispositivi virtuali Android).
  5. Assegna i test utilizzando il bin packing con priorità al tempo di elaborazione più lungo. Developer Device Platform ordina tutte le unità di test eseguibili in ordine decrescente di durata prevista (dalla più lenta alla più veloce) e inizializza un min-heap di shard vuoti ordinati in base alla durata accumulata. Prendendo un'unità di test alla volta, assegna il test rimanente più lento allo shard con la durata accumulata più bassa e aggiorna il totale di questo shard. La pianificazione dei test lenti "long-pole" li isola prima in shard separati, mentre i test più brevi riempiono i gap rimanenti per mantenere bilanciate le durate totali degli shard.

  6. Registra i tempi di passaggio e aggiorna Cloud Storage. Al termine di tutti gli shard, Developer Device Platform raccoglie le durate misurate da startTime a endTime degli scenari di test superati, elimina tutti i campioni più vecchi di 30 giorni in tutti i contesti dei dispositivi nel file YAML, rimuove tutti i record di contesto che non hanno campioni validi rimanenti e scrive il file YAML aggiornato in Cloud Storage utilizzando i nuovi tentativi di concorrenza ottimistica con corrispondenza della generazione.

Struttura del file YAML di sharding intelligente

Quando esegui una sessione con gcloud CLI, --smart-sharding-record-name specifica il nome file di base (esclusa l'estensione YAML) del record di temporizzazione archiviato nel bucket Cloud Storage del tuo progetto Google Cloud :

gs://BUCKET_NAME/automation/smart-sharding/RECORD_NAME.yaml

Sostituisci i seguenti segnaposto:

  • BUCKET_NAME: il nome del bucket Cloud Storage specificato con --bucket-name o <var>PROJECT_ID</var>-devicerun per impostazione predefinita (dove PROJECT_ID è l'ID progetto Google Cloud).
  • RECORD_NAME: l'identificatore del record passato a --smart-sharding-record-name senza l'estensione del file YAML (ad esempio, checkout-suite viene mappato a automation/smart-sharding/checkout-suite.yaml).

Esempio di record di tempistica YAML

L'esempio seguente mostra un file YAML di smart sharding (checkout-suite.yaml) contenente i record di tempistica per due contesti di Device Run: un dispositivo Android in esecuzione con Android Test Orchestrator e un dispositivo iOS:

records:
- shardingContext:
    deviceModel: shiba
    osVersion: '34'
  testCaseTimingRecords:
  - testCaseName: com.example.shop.CheckoutTest#testCompletePurchase
    timingSamples:
    - duration: 42.180s
      recordTime: '2026-11-08T14:20:11Z'
    - duration: 44.050s
      recordTime: '2026-11-09T16:45:03Z'
  - testCaseName: com.example.shop.CartTest#testApplyPromoCode
    timingSamples:
    - duration: 8.600s
      recordTime: '2026-11-08T14:20:11Z'
    - duration: 9.120s
      recordTime: '2026-11-09T16:45:03Z'
  conditionalOverheads:
  - condition: ANDROID_TEST_ORCHESTRATOR
    timingSamples:
    - duration: 2.850s
      recordTime: '2026-11-08T14:20:11Z'
    - duration: 3.150s
      recordTime: '2026-11-09T16:45:03Z'
- shardingContext:
    deviceModel: iphonese3
    osVersion: '18.4'
  testCaseTimingRecords:
  - testCaseName: ShopTests.CheckoutTests#testApplePaySheet
    timingSamples:
    - duration: 19.340s
      recordTime: '2026-11-09T17:10:29Z'

Riferimento dei campi YAML

Il file YAML di smart sharding serializza lo schema SuiteTiming utilizzando i nomi dei campi in camelCase. La tabella seguente descrive ogni campo del file:

Campo Tipo Descrizione
metadata Mappa (da string a string) Metadati facoltativi a livello di suite con coppia chiave-valore conservati tra gli aggiornamenti dell'aggregazione.
records Elenco degli oggetti Voci di temporizzazione per dispositivo (SuiteTimingWithContext), suddivise per modello hardware e versione del sistema operativo.
records[].shardingContext Oggetto Dimensioni hardware e del sistema operativo che definiscono un insieme di misurazioni dei tempi.
records[].shardingContext.deviceModel string Identificatore del modello del dispositivo su cui sono state registrate le tempistiche (ad esempio, shiba su Android o iphonese3 su iOS).
records[].shardingContext.osVersion string Versione del sistema operativo o dell'SDK del dispositivo (ad esempio, livello API Android '34' o versione iOS '18.4').
records[].testCaseTimingRecords Elenco degli oggetti Durate di esecuzione storiche per i singoli scenari di test superati in questo contesto.
records[].testCaseTimingRecords[].testCaseName string Identificatore del test completo nel formato package.ClassName#methodName (o package.ClassName se i metadati del metodo non sono presenti).
records[].testCaseTimingRecords[].timingSamples Elenco degli oggetti Elenco di 30 giorni consecutivi delle durate misurate per lo scenario di test, aggiunto dopo le esecuzioni riuscite.
timingSamples[].duration Stringa di durata Durata misurata formattata in secondi con precisione frazionaria facoltativa (ad esempio, 10s o 42.180s).
timingSamples[].recordTime Stringa timestamp Timestamp UTC RFC 3339 che indica quando Developer Device Platform ha registrato il campione (ad esempio, '2026-11-09T16:45:03Z').
records[].conditionalOverheads Elenco degli oggetti Overhead di esecuzione facoltativi misurati in modalità runner specifiche, con ambito shardingContext. Omesso quando non si applicano spese generali condizionali.
records[].conditionalOverheads[].condition string Identificatore della condizione di esecuzione. Valore supportato: ANDROID_TEST_ORCHESTRATOR.
records[].conditionalOverheads[].timingSamples Elenco degli oggetti Elenco mobile di 30 giorni di campioni di overhead per transizione registrati da shard idonei.

Informazioni sulle tempistiche di overhead di ANDROID_TEST_ORCHESTRATOR

Quando esegui i test di instrumentazione Android con --orchestrator-version, il file YAML di sharding smart include una voce conditionalOverheads con condition: ANDROID_TEST_ORCHESTRATOR. A differenza di testCaseTimingRecords, questi esempi di overhead non sono collegati a un singolo metodo di test o a uno shard numerato.

Cosa rappresenta un campione di durata dell'overhead

Quando Android Test Orchestrator è attivo, esegue ogni metodo di test nel proprio processo Instrumentation isolato. I timestamp dei singoli test startTime e endTime acquisiscono solo il tempo trascorso all'interno di ogni metodo di test, non includono l'intervallo tra i test dedicato all'arresto del processo dell'app precedente, alla cancellazione facoltativa dei dati del pacchetto (clearPackageData) e all'avvio di un nuovo processo Instrumentation per il test successivo.

Per misurare questo costo di transizione tra i test, Developer Device Platform esamina ogni shard superato che esegue due o più scenari di test (N > 1) e calcola:

  1. Intervallo di esecuzione totale dello shard: il tempo trascorso dal test startTime più recente nello shard al test endTime più recente nello shard.
  2. Durata totale degli scenari di test: la somma di (endTime - startTime) in tutti gli scenari di test N in questo shard.
  3. Overhead medio per transizione: poiché N test sequenziali hanno N - 1 transizioni tra i test, Developer Device Platform sottrae la somma delle durate dei test dall'intervallo dello shard e divide per N - 1:

    overhead_sample = max(0, total_span - total_test_duration) / (N - 1)
    

Ogni shard di test multiplo superato nel job contribuisce con un TimingSample a ANDROID_TEST_ORCHESTRATOR. Ad esempio, se una sessione viene eseguita su tre shard e ogni shard viene superato con almeno due scenari di test, la sessione aggiunge tre esempi di overhead con il recordTime della sessione. Gli shard che eseguono un solo scenario di test (N = 1) non hanno transizioni tra i test e non emettono un campione di overhead.

Perché l'overhead non è collegato a uno scenario di test o a uno shard

Developer Device Platform archivia i sample di ANDROID_TEST_ORCHESTRATOR a livello di shardingContext (deviceModel e osVersion) anziché per test o per shard per due motivi:

  • L'overhead dipende dal dispositivo e dal sistema operativo, non dalla logica del test. L'avvio del processo, l'inizializzazione del binder e la cancellazione dei dati del pacchetto richiedono all'incirca lo stesso tempo, indipendentemente dal metodo JUnit eseguito successivamente, mentre i raggruppamenti di shard cambiano dinamicamente ogni volta che cambiano i tempi di test o i conteggi degli shard.
  • Separare l'overhead preserva i tempi di test di riferimento puliti. Se mantieni l'overhead dell'isolamento dei processi fuori da testCaseTimingRecords, puoi attivare o disattivare --orchestrator-version tra le esecuzioni che condividono lo stesso record YAML senza distorcere le durate di esecuzione per test sottostanti.

In che modo Developer Device Platform utilizza l'overhead durante l'assegnazione degli shard

Quando --orchestrator-version viene impostato su una nuova sessione, Developer Device Platform calcola la media di 30 giorni dei campioni ANDROID_TEST_ORCHESTRATOR validi (avg_overhead) e la aggiunge alla durata media di 30 giorni di ogni scenario di test prima di calcolare i conteggi degli shard o di raggruppare gli shard:

expected_test_duration = avg_test_duration + avg_overhead

Se --orchestrator-version non è impostato nella sessione, avg_overhead è 0s e tutte le voci ANDROID_TEST_ORCHESTRATOR esistenti nel file YAML vengono ignorate per l'esecuzione.

L'aggiunta di avg_overhead a ogni scenario di test influisce sullo sharding in tre modi:

  • Numero di shard accurato per suite con molti test rapidi. Prendi in considerazione una suite di 60 test di instrumentazione in stile unità, ciascuno eseguito in 1s, con un overhead di transizione dell'orchestratore medio di 3s e una durata dello shard target di 2m (120s). Senza overhead, la durata totale prevista è di 60s, quindi tutti i 60 test vengono raggruppati in 1 shard che richiede quasi quattro minuti per essere completato (60s di esecuzione del test più 59 * 3s = 177s di transizioni dell'orchestratore). Aggiungendo l'overhead di 3s a ogni test (durata prevista di 4s per test o 240s in totale), Developer Device Platform alloca 2 shard (ceil(240s / 120s)) in modo che ogni shard termini vicino al target di due minuti.
  • Compressione degli shard bilanciata quando i conteggi dei test sono diversi. Durante il bin packing con priorità al tempo di elaborazione più lungo, uno shard a cui è assegnato un test UI 40s comporta un costo previsto di 43s (40s + 3s), mentre uno shard a cui sono assegnati 10 test 4s comporta un costo previsto di 70s (10 * (4s + 3s)). L'inclusione dell'overhead per test impedisce agli shard con molti test brevi di accumulare silenziosamente minuti di latenza di riavvio del processo non conteggiati.
  • Stime realistiche per i test appena aggiunti. Poiché i test non registrati in una suite esistente ereditano la durata media prevista dei test noti, che include già avg_overhead, i nuovi test tengono conto automaticamente dell'overhead dell'orchestratore alla prima esecuzione.

Informazioni sulla finestra di dati di 30 giorni e sul comportamento di esecuzione iniziale

Lo sharding smart non richiede 30 giorni di dati storici prima di iniziare a ottimizzare le esecuzioni dei test. Anche un singolo campione registrato attiva il calcolo degli shard basato sulla durata e il bin packing nella sessione successiva. Invece, 30 giorni è la finestra temporale e di conservazione continua che Developer Device Platform utilizza per leggere e aggiornare il record di tempistica YAML.

Perché lo sharding intelligente utilizza una finestra mobile di 30 giorni

Ogni volta che Developer Device Platform legge o aggiorna un file YAML di sharding smart, filtra tutti i TimingSample il cui recordTime risale a più di 30 giorni prima. Questa finestra di 30 giorni bilancia due obiettivi di progettazione:

  • Adattamento alle modifiche del codebase e limitazione delle dimensioni dei file. Le funzionalità dell'app, i flussi della UI e le implementazioni dei test si evolvono nel tempo. L'eliminazione automatica dei campioni più vecchi di 30 giorni impedisce che i tempi obsoleti, ad esempio quelli precedenti a un nuovo design dello schermo o a un refactoring del livello di rete, alterino le assegnazioni degli shard correnti. La rimozione delle voci scadute (e l'eliminazione dei contesti dei dispositivi che non hanno più esempi validi) mantiene anche il file YAML compatto e ben al di sotto del limite di 32 MB.
  • Smussamento della varianza tra le esecuzioni, supportando al contempo le suite settimanali. Una singola esecuzione del test può riscontrare rumore transitorio dovuto alla garbage collection, ai servizi di sistema in background o alla pianificazione dell'emulatore. La media dei campioni in un periodo di 30 giorni appiana i picchi isolati, conservando al contempo una cronologia sufficiente per consentire alle pipeline di integrazione continua notturne, settimanali o con cadenza sprint di mantenere i record di tempistica di warm-up tra un'esecuzione e l'altra.

Cosa aspettarsi nelle settimane uno e due

Se attivi lo sharding smart su una suite di test esistente oggi, i tempi di esecuzione seguono una curva di riscaldamento rapida anziché attendere settimane per migliorare:

  1. Prima esecuzione (avvio a freddo). Poiché il file YAML non esiste ancora in Cloud Storage, Developer Device Platform assegna a ogni unità di test eseguibile la stima predefinita di 30 secondi. Calcola il numero di shard come ceil(num_tests * 30s / target_duration) (limitato dal numero massimo di shard e dai limiti della piattaforma) e distribuisce i test tra gli shard, in modo simile allo sharding uniforme. In questa prima esecuzione:
    • Se i test durano in media molto meno di 30 secondi, l'esecuzione 1 potrebbe allocare più shard del necessario (fino a --smart-sharding-max-shard-count).
    • Se la tua suite contiene diversi test della UI di più minuti, due test lenti potrebbero finire nello stesso shard per caso, rendendo questo shard il collo di bottiglia per il tempo di completamento effettivo.
    • Al termine dell'esecuzione 1, Developer Device Platform crea il file YAML in Cloud Storage con le durate misurate dei test superati.
  2. Seconda esecuzione (subito dopo il completamento della prima esecuzione). Lo sharding smart è già attivo. Developer Device Platform legge le durate registrate dall'esecuzione 1, ricalcola il numero di shard in base al tempo di esecuzione reale della suite e isola prima i test più lenti in shard separati. In genere, la riduzione principale della durata della sessione in tempo reale e il dimensionamento corretto del numero di shard si verificano a partire dall'esecuzione 2, anche lo stesso giorno in cui attivi lo sharding intelligente.
  3. Remainder of week one and week two. Nelle successive esecuzioni, il bilanciamento degli shard continua a restringersi in tre casi specifici:
    • Smussamento della varianza di una singola esecuzione. Poiché ogni esecuzione successiva aggiunge un altro TimingSample, le fluttuazioni temporanee dell'esecuzione 1 vengono mediate, riducendo gli shard ritardatari che terminano leggermente dopo --smart-sharding-target-duration.
    • Completamento dei test dalle esecuzioni inizialmente non riuscite. Per evitare che arresti anomali rapidi o timeout dei test danneggino le medie storiche, Developer Device Platform registra i tempi solo per i test superati (e, su Android, solo per gli shard il cui stato complessivo della suite è PASSED). Qualsiasi test che non ha registrato un tempo nell'esecuzione 1 utilizza la durata media della suite nell'esecuzione 2, quindi passa al proprio tempo misurato una volta superato.
    • Aggiunta di nuovi test o modelli di dispositivi. Tutti i nuovi scenari di test di cui viene eseguito il commit durante le settimane uno e due utilizzano automaticamente la durata media prevista della suite anziché tornare al valore predefinito di 30 secondi. Se aggiungi un secondo modello --device alla sessione utilizzando lo stesso nome del record, la prima esecuzione utilizza le tempistiche del dispositivo esistente come fallback iniziale e poi registra una voce shardingContext dedicata per le esecuzioni successive.

Domande frequenti

Le seguenti domande riguardano scenari operativi comuni durante l'esecuzione dello sharding smart nelle pipeline CI/CD.

Passaggi successivi