Fragmentação inteligente no Device Run da Developer Device Platform

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:

  1. 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 records um shardingContext que corresponda ao deviceModel e ao osVersion do 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 entrada records disponí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.
  2. 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 recordTime está 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 de ANDROID_TEST_ORCHESTRATOR e adicionar essa média à duração esperada de cada caso de teste.
  3. 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 .xctest compilados e filtros .xctestrun no iOS, aplica todos os filtros --test-targets e exclui testes ignorados ou suprimidos (como @Ignore ou @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), JUnitParamsRunner ou TestParameterInjector) 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.
  4. 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-duration configurado (válido de 2m a 1h), 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 1 e 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 que 0.
    • O limite da plataforma (20 fragmentos para dispositivos físicos ou 200 fragmentos para dispositivos virtuais Android).
  5. 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.

  6. 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 startTime a endTime dos 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-name ou <var>PROJECT_ID</var>-devicerun por padrão (em que PROJECT_ID é o ID do projeto do Google Cloud).
  • RECORD_NAME: o identificador de registro transmitido para --smart-sharding-record-name sem a extensão de arquivo YAML (por exemplo, checkout-suite é mapeado para automation/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:

  1. Período total de execução do fragmento: o tempo decorrido do primeiro teste startTime no fragmento até o último teste endTime no fragmento.
  2. Duração total do caso de teste: a soma de (endTime - startTime) em todos os casos de teste N nesse fragmento.
  3. Sobrecarga média por transição: como N testes sequenciais têm N - 1 transições entre testes, a Developer Device Platform subtrai as durações dos testes somadas do período do fragmento e divide por N - 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 testCaseTimingRecords significa que é possível ativar ou desativar --orchestrator-version em 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 de 3s e uma duração de fragmento de destino de 2m (120s). Sem overhead, a duração total esperada é de 60s. Portanto, todos os 60 testes são agrupados em 1 fragmento que leva quase quatro minutos para ser concluído (60s de execução do teste mais 59 * 3s = 177s de transições do Orchestrator). Ao adicionar o overhead de 3s a cada teste (4s de duração esperada por teste ou 240s no total), a Developer Device Platform aloca 2 fragmentos (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 40s gera 43s de custo esperado (40s + 3s), enquanto um fragmento atribuído a 10 testes 4s gera 70s de 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:

  1. 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.
  2. 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.
  3. 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 entrada shardingContext dedicada para as execuções seguintes.

Perguntas frequentes

As perguntas a seguir abordam cenários operacionais comuns ao executar a fragmentação inteligente em pipelines de CI/CD.

A seguir