A fragmentação inteligente no Device Run da Developer Device Platform distribui testes de instrumentação do Android e XCTests do iOS em fragmentos paralelos usando tempos históricos de execução de teste armazenados no Cloud Storage. Ao contrário da fragmentação uniforme, que divide os casos de teste por contagem, independentemente de quanto tempo cada execução de teste leva, a fragmentação inteligente equilibra os fragmentos pela duração esperada para que os fragmentos paralelos terminem em torno do mesmo tempo de destino.
Neste documento, explicamos como o algoritmo de fragmentação inteligente calcula as contagens de fragmentos e atribui testes, descrevemos o esquema do registro de tempo YAML armazenado no seu bucket do Cloud Storage e respondemos a perguntas comuns sobre a sobrecarga do Android Test Orchestrator e a janela de dados contínua de 30 dias. Para instruções de linha de comando usando a Google Cloud CLI, consulte as instruções de instrumentação do Android e do XCTest do iOS.
Como funciona o algoritmo de fragmentação inteligente
A fragmentação não é equivalente ao número de testes que podem ser executados simultaneamente. É possível que os dispositivos disponíveis sejam menores que o limite de fragmentos no momento da solicitação. O número real de dispositivos simultâneos que podem ser alocados para um usuário pode ser menor do que o número de fragmentos especificado.
Quando você envia uma sessão com --sharding-option=smart na
CLI gcloud ou configura smartSharding na API REST,
a Developer Device Platform executa um fluxo de trabalho de seis etapas que abrange a criação da sessão, a execução do teste
e a conclusão:
- Ler dados históricos de tempo e corresponder ao contexto do dispositivo. Antes de
programar fragmentos, o agente de serviço do Device Run lê o
arquivo YAML de fragmentação inteligente no Cloud Storage. Ele pesquisa na lista
recordsumshardingContextque corresponda aodeviceModele aoosVersiondo job de destino (não diferencia maiúsculas de minúsculas). Se não houver uma correspondência exata para essa combinação de dispositivo e SO, a Developer Device Platform vai usar a primeira entradarecordsdisponível no arquivo. Se o arquivo YAML ainda não existir, a sessão vai prosseguir como uma inicialização a frio com histórico de tempo vazio. - Filtre as amostras para a janela contínua de 30 dias e calcule as durações
esperadas. Para o registro de contexto selecionado, a Developer Device Platform retém
apenas amostras de tempo em que o
recordTimeestá nos últimos 30 dias e calcula a duração média aritmética de cada caso de teste. Se o Android Test Orchestrator estiver ativado com--orchestrator-version, a Developer Device Platform também vai calcular a média de 30 dias das amostras de overhead deANDROID_TEST_ORCHESTRATORe adicionar essa média à duração esperada de cada caso de teste. - Descubra testes executáveis e atribua estimativas de substituição. No host de worker, a Developer Device Platform inspeciona estaticamente o pacote de teste, lendo arquivos DEX no APK de teste no Android ou símbolos
.xctestcompilados e filtros.xctestrunno iOS, aplica todos os filtros--test-targetse exclui testes ignorados ou suprimidos (como@Ignoreou@Suppress). Cada unidade de teste executável recebe uma duração esperada com base em três níveis:- Caso de teste gravado: usa a duração média histórica de 30 dias (mais
a sobrecarga média do Orchestrator quando o Android Test Orchestrator está ativado).
No Android, as classes JUnit parametrizadas (como as que usam
@RunWith(Parameterized.class),JUnitParamsRunnerouTestParameterInjector) são programadas como uma única unidade de nível de classe, com duração esperada igual à soma de todas as durações de método registradas para essa classe. - Caso de teste não registrado em um pacote atual: usa a duração média esperada de todos os casos de teste não zero registrados no registro correspondente.
- Inicialização a frio (sem histórico registrado): usa uma estimativa padrão de 30 segundos por unidade de teste.
- Caso de teste gravado: usa a duração média histórica de 30 dias (mais
a sobrecarga média do Orchestrator quando o Android Test Orchestrator está ativado).
No Android, as classes JUnit parametrizadas (como as que usam
Calcule a contagem de fragmentos. A Developer Device Platform soma as durações esperadas de todas as unidades de teste executáveis e divide pelo
--smart-sharding-target-durationconfigurado (válido de2ma1h), arredondando para o fragmento inteiro mais próximo:optimal_shards = max(1, ceil(total_expected_duration / target_duration))Em seguida, a Developer Device Platform define a contagem final de fragmentos entre
1e o menor dos seguintes limites:- O número total de unidades de teste executáveis (evitando fragmentos vazios).
- O valor de
--smart-sharding-max-shard-count, se definido como maior que0. - O limite da plataforma (
20fragmentos para dispositivos físicos ou200fragmentos para dispositivos virtuais Android).
Atribua testes usando o empacotamento de tempo de processamento mais longo primeiro. A Developer Device Platform classifica todas as unidades de teste executáveis em ordem decrescente de duração esperada (da mais lenta para a mais rápida) e inicializa um min-heap de fragmentos vazios ordenados por duração acumulada. Analisando uma unidade de teste por vez, ele atribui o teste restante mais lento ao fragmento com a menor duração acumulada e atualiza o total desse fragmento. Programar primeiro os testes lentos "long-pole" os isola em fragmentos separados, enquanto os testes mais curtos preenchem as lacunas restantes para manter as durações totais dos fragmentos equilibradas.
Registre os tempos de passagem e atualize o Cloud Storage. Depois que todos os fragmentos terminarem, a Developer Device Platform vai coletar as durações medidas de
startTimeaendTimedos casos de teste aprovados, remover as amostras com mais de 30 dias em todos os contextos de dispositivo no arquivo YAML, remover todos os registros de contexto que não têm amostras válidas restantes e gravar o arquivo YAML atualizado de volta no Cloud Storage usando novas tentativas de simultaneidade otimista com correspondência de geração.
Estrutura do arquivo YAML de fragmentação inteligente
Quando você executa uma sessão com a CLI gcloud,
--smart-sharding-record-name especifica o nome de arquivo base (excluindo a extensão
YAML) do registro de tempo armazenado no bucket do Cloud Storage
do Google Cloud projeto:
gs://BUCKET_NAME/automation/smart-sharding/RECORD_NAME.yaml
Substitua os seguintes marcadores de posição:
BUCKET_NAME: o nome do bucket do Cloud Storage especificado com--bucket-nameou<var>PROJECT_ID</var>-devicerunpor padrão (em quePROJECT_IDé o ID do projeto do Google Cloud).RECORD_NAME: o identificador de registro transmitido para--smart-sharding-record-namesem a extensão de arquivo YAML (por exemplo,checkout-suiteé mapeado paraautomation/smart-sharding/checkout-suite.yaml).
Exemplo de registro de tempo YAML
O exemplo a seguir mostra um arquivo YAML de fragmentação inteligente (checkout-suite.yaml) que contém registros de tempo para dois contextos de Device Run: um dispositivo Android em execução com o Android Test Orchestrator e um 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'
Referência de campo YAML
O arquivo YAML de fragmentação inteligente serializa o esquema SuiteTiming usando nomes de campo
camelCase. A tabela a seguir descreve cada campo no arquivo:
| Campo | Tipo | Descrição |
|---|---|---|
metadata |
Mapa (string a string) |
Metadados opcionais de chave-valor no nível do pacote preservados em atualizações de agregação. |
records |
Lista de objetos | Entradas de tempo por dispositivo (SuiteTimingWithContext), particionadas por modelo de hardware e versão do SO. |
records[].shardingContext |
Objeto | Dimensões de hardware e SO que abrangem um conjunto de medições de tempo. |
records[].shardingContext.deviceModel |
string |
Identificador do modelo do dispositivo em que os tempos foram registrados (por exemplo, shiba no Android ou iphonese3 no iOS). |
records[].shardingContext.osVersion |
string |
Versão do SO ou do SDK do dispositivo (por exemplo, nível da API do Android '34' ou versão do iOS '18.4'). |
records[].testCaseTimingRecords |
Lista de objetos | Durações de execução históricas para casos de teste individuais aprovados neste contexto. |
records[].testCaseTimingRecords[].testCaseName |
string |
Identificador de teste totalmente qualificado no formato package.ClassName#methodName (ou package.ClassName se os metadados do método estiverem ausentes). |
records[].testCaseTimingRecords[].timingSamples |
Lista de objetos | Lista contínua de 30 dias de durações medidas para o caso de teste, anexada após as execuções bem-sucedidas. |
timingSamples[].duration |
String de duração | Duração medida formatada em segundos com precisão fracionária opcional (por exemplo, 10s ou 42.180s). |
timingSamples[].recordTime |
String de carimbo de data/hora | Carimbo de data/hora UTC RFC 3339 que indica quando a Developer Device Platform registrou a amostra (por exemplo, '2026-11-09T16:45:03Z'). |
records[].conditionalOverheads |
Lista de objetos | Sobrecargas de execução opcionais medidas em modos de execução específicos, com escopo para shardingContext. Omitido quando não há custos indiretos condicionais. |
records[].conditionalOverheads[].condition |
string |
Identificador da condição de execução. Valor compatível: ANDROID_TEST_ORCHESTRATOR. |
records[].conditionalOverheads[].timingSamples |
Lista de objetos | Lista contínua de 30 dias de amostras de sobrecarga por transição registradas de fragmentos qualificados. |
Entender os tempos de overhead do ANDROID_TEST_ORCHESTRATOR
Quando você executa testes de instrumentação do Android com --orchestrator-version, o
arquivo YAML de fragmentação inteligente inclui uma entrada conditionalOverheads com
condition: ANDROID_TEST_ORCHESTRATOR. Ao contrário de testCaseTimingRecords, essas
amostras de overhead não estão anexadas a um método de teste individual ou a um fragmento
numerado.
O que uma amostra de duração de overhead representa
Quando o Android Test
Orchestrator
está ativado, ele executa cada método de teste no próprio processo Instrumentation
isolado. Os carimbos de data/hora de teste individual startTime e endTime capturam apenas o
tempo gasto dentro de cada método de teste. Eles não incluem o intervalo entre testes gasto
interrompendo o processo anterior do app, limpando opcionalmente os dados do pacote
(clearPackageData) e iniciando um novo processo Instrumentation para o
próximo teste.
Para medir esse custo de transição entre testes, a Developer Device Platform inspeciona cada
fragmento aprovado que executa dois ou mais casos de teste (N > 1) e calcula:
- Período total de execução do fragmento: o tempo decorrido do
primeiro teste
startTimeno fragmento até o último testeendTimeno fragmento. - Duração total do caso de teste: a soma de
(endTime - startTime)em todos os casos de testeNnesse fragmento. Sobrecarga média por transição: como
Ntestes sequenciais têmN - 1transições entre testes, a Developer Device Platform subtrai as durações dos testes somadas do período do fragmento e divide porN - 1:overhead_sample = max(0, total_span - total_test_duration) / (N - 1)
Cada fragmento de teste múltiplo aprovado no job contribui com um TimingSample para
ANDROID_TEST_ORCHESTRATOR. Por exemplo, se uma sessão for executada em três fragmentos
e cada um deles for aprovado com pelo menos dois casos de teste, essa sessão vai anexar três
amostras de overhead com o recordTime da sessão. Os fragmentos que executam apenas um caso de teste (N = 1) têm zero transições entre testes e não emitem uma amostra de overhead.
Por que a sobrecarga não está vinculada a um caso de teste ou fragmento
A Developer Device Platform armazena amostras de ANDROID_TEST_ORCHESTRATOR no nível
shardingContext (deviceModel e osVersion), em vez de por teste ou
por fragmento, por dois motivos:
- A sobrecarga depende do dispositivo e do SO, não da lógica de teste. A inicialização do processo, a inicialização do binder e a limpeza de dados de pacotes levam aproximadamente o mesmo tempo, independentemente do método JUnit executado em seguida, enquanto os agrupamentos de fragmentos mudam dinamicamente sempre que os tempos de teste ou as contagens de fragmentos mudam.
- Separar a sobrecarga preserva os tempos de teste de referência limpos. Manter
a sobrecarga de isolamento de processos fora de
testCaseTimingRecordssignifica que é possível ativar ou desativar--orchestrator-versionem execuções que compartilham o mesmo registro YAML sem distorcer as durações de execução subjacentes por teste.
Como a Developer Device Platform usa a sobrecarga durante a atribuição de fragmentos
Quando --orchestrator-version é definido em uma nova sessão, a Developer Device Platform calcula a média de 30 dias de amostras válidas de ANDROID_TEST_ORCHESTRATOR (avg_overhead) e a adiciona à duração média de 30 dias de cada caso de teste antes de calcular as contagens de fragmentos ou empacotar fragmentos:
expected_test_duration = avg_test_duration + avg_overhead
Se --orchestrator-version não estiver definido na sessão, avg_overhead será 0s e
todas as entradas ANDROID_TEST_ORCHESTRATOR no arquivo YAML serão ignoradas
para essa execução.
Adicionar avg_overhead a cada caso de teste afeta a fragmentação de três maneiras:
- Contagem de fragmentos precisa para pacotes com muitos testes rápidos. Considere um pacote
de 60 testes de instrumentação de estilo de unidade, cada um executado em
1s, com uma sobrecarga média de transição do orquestrador de3se uma duração de fragmento de destino de2m(120s). Sem overhead, a duração total esperada é de60s. Portanto, todos os 60 testes são agrupados em1fragmento que leva quase quatro minutos para ser concluído (60sde execução do teste mais59 * 3s = 177sde transições do Orchestrator). Ao adicionar o overhead de3sa cada teste (4sde duração esperada por teste ou240sno total), a Developer Device Platform aloca2fragmentos (ceil(240s / 120s)) para que cada um termine perto da meta de dois minutos. - Empacotamento de fragmentos equilibrado quando as contagens de teste são diferentes. Durante o empacotamento de tempo de processamento mais longo, um fragmento atribuído a um teste de UI
40sgera43sde custo esperado (40s + 3s), enquanto um fragmento atribuído a 10 testes4sgera70sde custo esperado (10 * (4s + 3s)). Incluir a sobrecarga por teste evita que fragmentos com muitos testes curtos acumulem silenciosamente minutos de latência de reinicialização de processo não contabilizados. - Estimativas realistas para testes recém-adicionados. Como os testes não registrados em
um pacote herdam a duração média esperada dos testes conhecidos, que
já inclui
avg_overhead, os novos testes consideram automaticamente a sobrecarga do orquestrador na primeira execução.
Entender a janela de dados de 30 dias e o comportamento da execução inicial
A fragmentação inteligente não exige 30 dias de dados históricos antes de começar a otimizar as execuções de teste. Mesmo uma única amostra gravada ativa o cálculo de fragmentos com base na duração e o empacotamento na sessão seguinte. Em vez disso, 30 dias é a janela de retenção e janela de lookback contínua que a Developer Device Platform usa ao ler e atualizar o registro de tempo do YAML.
Por que a fragmentação inteligente usa uma janela contínua de 30 dias
Sempre que a Plataforma de Dispositivos para Desenvolvedores lê ou atualiza um arquivo YAML de fragmentação inteligente,
ela filtra qualquer TimingSample em que o recordTime tenha mais de 30 dias.
Essa janela de 30 dias equilibra duas metas de engenharia:
- Adaptação às mudanças na base de código e limitação do tamanho do arquivo. Os recursos do app, os fluxos UI e as implementações de teste evoluem com o tempo. A remoção automática de amostras com mais de 30 dias impede que tempos obsoletos, como os de antes de uma reformulação de tela ou de uma refatoração da camada de rede, distorçam as atribuições atuais de fragmentos. A remoção de entradas expiradas (e a eliminação de contextos de dispositivos que não têm mais amostras válidas) também mantém o arquivo YAML compacto e bem abaixo do limite de 32 MB.
- Suavização da variação entre execuções com suporte a conjuntos semanais. Uma única execução de teste pode sofrer ruídos temporários da coleta de lixo, de serviços do sistema em segundo plano ou da programação do emulador. A média de amostras em uma janela de 30 dias suaviza picos pontuais, mantendo histórico suficiente para que pipelines de integração contínua noturnos, semanais ou de sprint mantenham registros de tempo de aquecimento entre as execuções.
O que esperar nas semanas um e dois
Se você ativar a fragmentação inteligente em um pacote de testes atual, os tempos de execução vão seguir uma curva de aquecimento rápido em vez de esperar semanas para melhorar:
- Primeira execução (inicialização a frio). Como o arquivo YAML ainda não existe no Cloud Storage, a Developer Device Platform atribui a cada unidade de teste executável a estimativa padrão de 30 segundos. Ele calcula a contagem de fragmentos
como
ceil(num_tests * 30s / target_duration)(limitada pela contagem máxima de fragmentos e pelos limites da plataforma) e distribui os testes entre os fragmentos, de forma semelhante à fragmentação uniforme. Nessa primeira execução:- Se os testes durarem em média muito menos de 30 segundos, a Execução 1 poderá alocar
mais fragmentos do que o necessário (até
--smart-sharding-max-shard-count). - Se o conjunto tiver vários testes UI de vários minutos, dois testes lentos podem acabar no mesmo fragmento por acaso, tornando esse fragmento o gargalo para o tempo de conclusão do relógio.
- Quando a Execução 1 é concluída, a Developer Device Platform cria o arquivo YAML no Cloud Storage com as durações medidas dos testes aprovados.
- Se os testes durarem em média muito menos de 30 segundos, a Execução 1 poderá alocar
mais fragmentos do que o necessário (até
- Segunda execução (imediatamente após a conclusão da Execução 1). A fragmentação inteligente já está ativa. A Developer Device Platform lê as durações registradas pela Execução 1, recalcula a contagem de fragmentos com base no tempo de execução real do seu pacote e isola os testes mais lentos em fragmentos separados primeiro. Normalmente, você vê a redução principal na duração da sessão de tempo de relógio e no dimensionamento correto da contagem de fragmentos a partir da execução 2, mesmo no mesmo dia em que ativa a fragmentação inteligente.
- Restante da semana um e semana dois. Nas próximas execuções, o equilíbrio de fragmentos
continua a se estreitar em três casos específicos:
- Suavização da variância de uma única execução. Como cada execução adiciona outro
TimingSample, as flutuações temporárias da Execução 1 são calculadas, reduzindo os fragmentos atrasados que terminam um pouco depois de--smart-sharding-target-duration. - Preenchimento de testes de execuções que falharam inicialmente. Para evitar que falhas rápidas ou tempos limite de teste corrompam as médias históricas, a Developer Device Platform registra os tempos apenas para testes aprovados (e, no Android, apenas de fragmentos em que o status geral do pacote é
PASSED). Qualquer teste que não tenha registrado um tempo na Execução 1 usa a duração média do pacote na Execução 2 e, em seguida, muda para o próprio tempo medido quando é aprovado. - Adicionar novos testes ou modelos de dispositivo. Todos os novos casos de teste confirmados
durante as semanas um e dois usam automaticamente a duração média esperada
do pacote, em vez de reverter para o padrão de 30 segundos. Se você adicionar um
segundo modelo
--deviceà sessão usando o mesmo nome de registro, a primeira execução dele vai usar os tempos do dispositivo atual como um substituto inicial e, em seguida, vai registrar uma entradashardingContextdedicada para as execuções seguintes.
- Suavização da variância de uma única execução. Como cada execução adiciona outro
Perguntas frequentes
As perguntas a seguir abordam cenários operacionais comuns ao executar a fragmentação inteligente em pipelines de CI/CD.
A seguir
- Saiba mais sobre o executor de testes TestParameterInjector.
- Configure as flags de fragmentação inteligente em Executar um teste de instrumentação do Android.
- Configure as execuções de teste do iOS em Executar um XCTest do iOS.
- Verifique as permissões de bucket entre projetos para o agente de serviço em Compartilhar seus buckets do Cloud Storage com a Developer Device Platform.
- Inspecione os artefatos de registro e
junit.xmlpor fragmento em Encontrar os resultados do teste da Developer Device Platform.