Tradução de comandos e flags da plataforma de dispositivos do desenvolvedor para o Firebase Test Lab

A Plataforma de dispositivos para desenvolvedores (DDP) substitui o console legado do Firebase Test Lab e os fluxos de trabalho da CLI do Test Lab por uma CLI de teste unificada, de alta performance e segura Google Cloud-first: gcloud beta device-run

Este guia fornece traduções de linha de comando e mapeamentos de flags do Test Lab (ou Flank) para o DDP. Use estas orientações para migrar seus testes manualmente. Consulte Migrar do Firebase Test Lab para a plataforma de dispositivos do desenvolvedor para conhecer ferramentas de automação, benefícios, principais diferenças e dicas de migração.

Migração de fragmentação

O DDP moderniza as configurações de fragmentação substituindo nativamente a fragmentação inteligente complexa do Flank baseada no Cloud Storage e a fragmentação uniforme do Test Lab.

Fragmentação uniforme

  • Defina --sharding-option=uniform.

  • Defina --uniform-sharding-count={count} (1 a 20 para físico, 1 a 200 para virtual).

  • Firebase Test Lab legado: --num-uniform-shards {N}

  • CLI do DDP: --sharding-option=uniform --uniform-sharding-count={N}

Fragmentação inteligente

  • Defina --sharding-option=smart.
  • Defina --smart-sharding-target-duration={duration} (por exemplo, 2m, 10m, 1h; intervalo válido: 2m a 1h).
  • Defina --smart-sharding-record-name={record_name} (aponta para o registro de rastreamento YAML em --bucket-name em automation/smart-sharding/).
  • Defina --smart-sharding-max-shard-count={max_count} (limite máximo opcional: 0 a 20 para dispositivos físicos e 0 a 200 para virtuais).

Usando metadados históricos de tempo de 30 dias:

  • Flank legado:

    max-test-shards: 10
shard-time: 120
smart-flank-gcs-path: gs://my-bucket/smart-sharding/timing-record.yaml

  • CLI do DDP:

    --sharding-option=smart \
--smart-sharding-max-shard-count=10 \
--smart-sharding-target-duration=2m \
--smart-sharding-record-name=timing-record \
--bucket-name=my-bucket

Configuração declarativa do YAML (--flags-file)

Para configurações complexas ou equipes que preferem manter arquivos com controle de versões em vez de comandos longos do terminal, o gcloud oferece um pré-processador de argumentos --flags-file universal (consulte $ gcloud topic flags-file):

gcloud beta device-run sessions submit instrumentation --flags-file=device-run-flags.yaml

Confira um exemplo que demonstra uma lista de vários valores e flags de dicionário:

# device-run-flags.yaml
--device:
  -   mediumphone-arm-32
  -   shiba-36
--apps:
  -   app-debug.apk
  -   test-helper.apk
--test: app-debug-androidTest.apk
--bucket-name: my-bucket
--sharding-option: smart
--smart-sharding-target-duration: 2m
--smart-sharding-record-name: timing-record
--paths-to-pull:
  -   /sdcard/screenshots
  -   /sdcard/coverage.ec
--additional-test-options:
  coverage: "true"
  clearPackageData: "true"

Exemplos de tradução de comandos de ponta a ponta

Confira exemplos concretos dessas traduções padrão e complexas.

Exemplo: executar um teste de instrumentação padrão

CLI legada do Firebase:

gcloud firebase test android run \
  --app=app-debug.apk \
  --test=app-debug-androidTest.apk \
  --device model=shiba,version=36 \
  --timeout=5m \
  --num-flaky-test-attempts=2 \
  --directories-to-pull=/sdcard/screenshots \
  --environment-variables key=value

Tradução da CLI do DDP:

gcloud beta device-run sessions submit instrumentation \
  --device=shiba-36 \
  --apps=app-debug.apk \
  --test=app-debug-androidTest.apk \
  --instrumentation-timeout=5m \
  --flaky-test-attempts=3 \
  --paths-to-pull=/sdcard/screenshots \
  --additional-test-options key=value

Exemplo: migrar uma configuração YAML de flanco complexa

Configuração legada do Flank:

app: app-debug.apk
test: app-debug-androidTest.apk
device:
  -   model: shiba
    version: 36
shard-time: 120
smart-flank-gcs-path: gs://my-bucket/smart-sharding/timing-record.yaml

Tradução da CLI do DDP:

gcloud beta device-run sessions submit instrumentation \
  --device=shiba-36 \
  --apps=app-debug.apk \
  --test=app-debug-androidTest.apk \
  --bucket-name=my-bucket \
  --sharding-option=smart \
  --smart-sharding-target-duration=2m \
  --smart-sharding-record-name=timing-record

Pós-execução e recuperação de resultados

Como o DDP não é iniciado com uma UI gráfica da Web (como o console do Firebase legado), os desenvolvedores precisam gerenciar, descrever e inspecionar os resultados diretamente usando a CLI ou as APIs REST programáticas:

# 1. List active and completed test sessions
gcloud beta device-run sessions list

# 2. Get a summary and direct Cloud Storage bucket link of a session's results
gcloud beta device-run sessions describe session-number

# 3. Get detailed metadata and print full results
gcloud beta device-run sessions describe session-number --full

# 4. Cancel a running session (replaces console cancellation)
gcloud beta device-run sessions cancel session-number

Referência de mapeamento de flags

Confira o mapeamento de flags para migrar configurações de teste do Flank ou gcloud firebase test android/ios run para o novo comando gcloud beta device-run sessions submit instrumentation do DDP.

Parâmetros e recursos principais

Parâmetro legado (Test Lab / Flank) Parâmetro de DDP de destino Formato / lógica de conversão
--app --apps Lista. Se vários APKs/AABs de aplicativos forem fornecidos, transmita todos eles para --apps na ordem em que serão instalados no dispositivo. O caminho pode ser local ou no Cloud Storage (gs://...).
--test --test OBRIGATÓRIO String. Caminho para o APK de teste que contém testes de instrumentação, seja local ou no Cloud Storage.
--client-details --labels Dicionário de key=value pares a serem anexados à sessão de teste.

Configurador do dispositivo e segmentação

Parâmetro legado (Test Lab / Flank) Parâmetro de DDP de destino Formato / lógica de conversão
--device model={M},version={V} --device={M}-{V} String OBRIGATÓRIA que mapeia o modelo e a versão do SO para uma única string de ID --device. A flag --device da DDP aceita vários IDs de dispositivo separados por vírgulas (por exemplo, --device=shiba-34,tokay-36) ou várias flags --device, cada uma especificando um ID de dispositivo diferente (por exemplo, --device=shiba-34 --device=tokay-36).
--device locale={L} --locale={L} String. Mapeia a localidade do dispositivo para a flag --locale de nível superior (language-region, por exemplo, --locale=en-US) para mudar o dispositivo antes de executar o teste.
--device orientation={O} --orientation={O} String. Mapeia a orientação do dispositivo para a flag --orientation de nível superior (portrait ou landscape).
N/A --coordinates String. Simula coordenadas de localização do GPS do dispositivo (por exemplo, --coordinates=37.4220,-122.0841).

Controle de execução e instabilidade

Parâmetro legado (Test Lab / Flank) Parâmetro de DDP de destino Formato / lógica de conversão
--num-flaky-test-attempts {R} --flaky-test-attempts {A} Número inteiro. O número máximo de tentativas de execução por fragmento de teste. Converta a contagem de novas tentativas R no limite total de tentativas A: A = R +1 (o padrão é 1).
N/A --flaky-test-parallel-retry Boolean. Se as falhas de teste devem ser repetidas em paralelo (o padrão é false para execução sequencial).
N/A --flaky-test-retry-level String. Define se a nova tentativa será feita no nível shard ou test individual (o padrão é shard).
--async --async Boolean. Maps 1:1. Por padrão, o comando é executado de forma síncrona. Transmita isso para voltar ao terminal imediatamente. Sai imediatamente após o upload do arquivo e imprime os IDs da operação e da sessão.

Test runner e destinos

Parâmetro legado (Test Lab / Flank) Parâmetro de DDP de destino Formato / lógica de conversão
--environment-variables --additional-test-options Dicionário de opções transmitidas ao executor de testes de instrumentação. Não é permitido usar formatos compatíveis com --test-targets.
--test-targets --test-targets Dicionário de destinos de teste ou filtros de destino a serem executados. Cada destino precisa estar totalmente qualificado com o nome do pacote ou da classe, compatível com chaves como package, notPackage, class, notClass, annotation, notAnnotation e size. Os formatos testfile ou notTestfile não são aceitos.
--use-orchestrator --orchestrator-version Se o Android Test Orchestrator será usado. Usa auto (orquestrador padrão) ou uma string de versão específica (por exemplo, 1.6). As versões disponíveis podem ser consultadas usando gcloud beta device-run software-versions list.
--test-runner-class --test-runner-class String. A classe totalmente qualificada do executor de testes de instrumentação (por exemplo, com.foo.MyRunner) a ser usado. Se não for especificado, uma classe executora padrão será determinada por meio de exame no manifesto do aplicativo.
--directories-to-pull --paths-to-pull Lista. Diretórios para fazer o download do dispositivo após a execução do teste.
--other-files --other-files-to-push Dictionary. Lista SOURCE=DEST separada por vírgulas de arquivos auxiliares para enviar ao dispositivo antes da execução do teste.

Saída e armazenamento

Parâmetro legado (Test Lab / Flank) Parâmetro de DDP de destino Formato / lógica de conversão
--results-bucket --bucket-name String. Bucket do Cloud Storage em que os artefatos de teste, incluindo arquivos de entrada locais, arquivos de saída de teste e registros de tempo de fragmentação inteligente, são enviados por upload (o padrão é gs://[PROJECT_ID]-devicerun se não for especificado).
--results-dir Gerenciada automaticamente Não compatível. Os subcaminhos são organizados automaticamente no Cloud Storage em automation/sessions/{session_id}/.

Configuração de fragmentação

Parâmetro legado (Test Lab / Flank) Parâmetro de DDP de destino Formato / lógica de conversão
--num-uniform-shards {N} --sharding-option=uniform --uniform-sharding-count={N} String e Integer. A configuração combinada de flags ativa a estratégia de fragmentação uniforme e define a contagem máxima de fragmentos (intervalo de contagem válido: 1 a 20 físicos, 1 a 200 virtuais).
Flanco --max-test-shards {N} --sharding-option=smart --smart-sharding-max-shard-count={N} String e Integer. A configuração combinada de flags ativa a estratégia de fragmentação inteligente e define a contagem máxima de fragmentos (intervalo de contagem válido: 0 a 20 físicos, 0 a 200 virtuais).
Flanco --shard-time {S} --sharding-option=smart --smart-sharding-target-duration={S} OBRIGATÓRIO String. Ativa o sharding inteligente com o tempo de execução desejado (por exemplo, 2m, 10m, 1h). Intervalo válido: 2m a 1h.
Flanco --smart-flank-gcs-path --smart-sharding-record-name={name} --bucket-name={bucket} OBRIGATÓRIO String. Nome do YAML de registro de fragmentação (excluindo a extensão do arquivo) em --bucket-name em smart-sharding/ no Cloud Storage.

Flags específicas do Android

Use esta tabela para mapear flags legadas de gcloud firebase test android run para os novos equivalentes de device-run:

Parâmetro legado (firebase android) Parâmetro de DDP de destino Formato / lógica de conversão
--additional-apks --apps Lista. Mescle outros valores de lista diretamente na lista principal --apps.
N/A --bugreport String. Colete um bugreport completo do dispositivo (valores: always, on-failure).
N/A --dumpsys String. Colete o estado do sistema usando dumpsys (valores: always, on-failure).
--timeout --instrumentation-timeout Duração (por exemplo, 10m, 20s, 1h). Intervalo válido: 1m a 3h (padrão: 5m).
--record-video --video String. Quando gravar um vídeo da tela do dispositivo durante o teste.Os valores válidos são always ou on-failure.

Flags específicas do iOS

Use esta tabela para mapear flags legadas de gcloud firebase test ios run para os novos equivalentes de device-run:

Parâmetro legado (firebase ios) Parâmetro de DDP de destino Formato / lógica de conversão
--test --test Caminho para o ZIP do XCTest criado.
--device model={M},version={V} --device={M}-{V} String de ID do dispositivo de destino.
--timeout --xctest-timeout Duração (por exemplo, 5m). Intervalo: de 1m a 1h.
--xcode-version --xcode-version ID do catálogo ou string de versão do Xcode a ser usada (por exemplo, xcode-16-4 ou 16.4). As versões disponíveis podem ser consultadas usando gcloud beta device-run software-versions list.
--results-bucket --bucket-name Bucket do GCS de destino personalizado.
--async --async Síncrono por padrão, transmita para sair imediatamente.
--other-files --other-files-to-push Dicionário no formato SOURCE=BUNDLE_ID:DEST.
--directories-to-pull --paths-to-pull Lista no formato BUNDLE_ID:DEVICE_PATH.
--additional-ipas --additional-apps Lista de IPAs auxiliares a serem instaladas antes do teste.
--xctestrun-file --xctestrun-file Caminho para a lista de propriedades .xctestrun personalizada.
--num-flaky-test-attempts --flaky-test-attempts Contagem de números inteiros de novas tentativas (por exemplo, 3).
--client-details --labels Pares de chave-valor (KEY=VALUE).

Feedback e dúvidas

Entre em contato para informar bugs e solicitar recursos ou participe do nosso fórum de discussão.