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

A Developer Device Platform (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 alto desempenho e segura, priorizando oGoogle Cloud: 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 Developer Device Platform para conferir 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 baseada no Cloud Storage do Flank 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 da 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: de 2m a 1h).
  • Defina --smart-sharding-record-name={record_name} (aponta para o registro de rastreamento YAML dentro de --bucket-name em automation/smart-sharding/).
  • Defina --smart-sharding-max-shard-count={max_count} (limite máximo opcional: 0 a 20 para físico, 0 a 200 para virtual).

Usando metadados de tempo históricos 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 de terminal longos, o gcloud fornece um pré-processador de argumentos --flags-file universal (consulte $ gcloud topic flags-file):

Android

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

iOS

gcloud alpha device-run sessions submit xctest --flags-file=device-run-flags.yaml

Veja um exemplo que demonstra uma lista de vários valores e sinalizações de dicionário:

Android

# 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"

iOS

# device-run-flags.yaml
--device:

    -   iphonese3-18-4
    -   iphone16pro-18-3
--test: MyTests.zip
--additional-apps:
    -   helper-app.ipa
--xcode-version: '16.4'
--xctest-timeout: 15m
--other-files-to-push:
  /local/path/test-config.json: com.example.app:/Documents/test-config.json
--paths-to-pull:
    -   com.example.app:/Documents/screenshots
--labels:
  env: staging
  team: mobile-qa

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

Confira estas traduções padrão e complexas para ver exemplos concretos.

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 complexa do Flank

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 legado do Firebase), 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 sinalizações

Confira o mapeamento de flags para migrar configurações de teste do Flank ou do gcloud firebase test android/ios run para os novos comandos gcloud beta device-run sessions submit instrumentation e gcloud alpha device-run sessions submit xctest do DDP.

Parâmetros e recursos principais

Parâmetro legado (Test Lab / Flank) Parâmetro de DDP desejado Lógica de formato / conversão
Flanco --project --project Sinalização global padrão do Google Cloud (--project=PROJECT_ID) ou configuração ativa da Google Cloud CLI.
--client-details --labels Dicionário de pares key=value a serem anexados à sessão de teste.
--other-files --other-files-to-push Dictionary. Arquivos auxiliares para enviar ao dispositivo antes da execução de teste. Inverte a ordem legada de DEST=SOURCE para SOURCE=DEST (SOURCE=DEVICE_PATH no Android; SOURCE=BUNDLE_ID:DEVICE_PATH no iOS).

Configurador do dispositivo e segmentação

Parâmetro legado (Test Lab / Flank) Parâmetro de DDP desejado Lógica de formato / conversão
--device model={M},version={V} --device={M}-{V} OBRIGATÓRIO String que mapeia o modelo e a versão do SO para uma única string de ID --device. A flag --device do DDP aceita vários IDs de dispositivo separados por vírgulas (por exemplo, --device=shiba-34,tokay-36 ou --device=iphone16pro-18-3) ou várias flags --device, cada uma especificando um ID de dispositivo diferente (por exemplo, --device=shiba-34 --device=tokay-36).

Controle de execução e instabilidade

Parâmetro legado (Test Lab / Flank) Parâmetro de DDP desejado Lógica de formato / conversão
--async --async Boolean. Maps 1:1. O comando é executado de forma síncrona por padrão. Transmita isso para retornar ao terminal imediatamente. Sai imediatamente após o upload do arquivo e imprime os IDs de operação e sessã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 em limite total de tentativas A: A = R + 1 (o padrão é 1).

Saída e armazenamento

Parâmetro legado (Test Lab / Flank) Parâmetro de DDP desejado Lógica de formato / 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 (o padrão é gs://[PROJECT_ID]-devicerun se não for especificado).
--results-dir Gerenciadas automaticamente Não compatível. Os subcaminhos são organizados automaticamente no Cloud Storage em automation/sessions/{session_id}/.
--directories-to-pull --paths-to-pull List. Arquivos ou diretórios para download do dispositivo após a execução de teste (DEVICE_PATH no Android; BUNDLE_ID:DEVICE_PATH no iOS).

Configuração de fragmentação

Parâmetro legado (Test Lab / Flank) Parâmetro de DDP desejado Lógica de formato / conversão
--num-uniform-shards {N} --sharding-option=uniform --uniform-sharding-count={N} String e Integer. A configuração de flag combinada 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 de flag combinada 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 a fragmentação inteligente com o tempo de execução desejado (por exemplo, 2m, 10m, 1h). Intervalo válido: de 2m a 1h.
Flanco --smart-flank-gcs-path --smart-sharding-record-name={name} --bucket-name={bucket} OBRIGATÓRIO String. Nome do YAML do 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 as flags legadas do gcloud firebase test android run e do Flank para Android para os novos equivalentes do gcloud beta device-run sessions submit instrumentation:

Tipo de teste Grupo de atributos Parâmetro legado (firebase android / Flank) Parâmetro de DDP desejado Lógica de formato / conversão
Android comum Parâmetros e recursos principais --app --apps List. Se vários APKs/AABs de aplicativo forem fornecidos, transmita todos para --apps na ordem em que serão instalados no dispositivo. O caminho pode ser local ou no Cloud Storage (gs://...).
Android comum Parâmetros e recursos principais --additional-apks --apps List. Mescle outros valores de lista diretamente na lista principal --apps.
Android comum Parâmetros e recursos principais --obb-files --other-files-to-push Dicionário no formato SOURCE=DEST. Envie arquivos OBB diretamente para o caminho do dispositivo de destino (/sdcard/Android/obb/{package_name}/).
Android comum Configurador do dispositivo e segmentação --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 o dispositivo antes de executar o teste.
Android comum Configurador do dispositivo e segmentação --device orientation={O} --orientation={O} String. Mapeia a orientação do dispositivo para a flag --orientation de nível superior (portrait ou landscape).
Android comum Configurador do dispositivo e segmentação N/A --coordinates String. Simula as coordenadas de localização GPS do dispositivo (por exemplo, --coordinates=37.4220,-122.0841).
Android comum Controle de execução e instabilidade --grant-permissions Padrão automatizado Automatizado. As permissões de execução são concedidas automaticamente por padrão (equivalente a --grant-permissions=all).
Android comum Saída e armazenamento N/A --dumpsys String. Coletar o estado do sistema usando dumpsys (valores: always, on-failure).
Android comum Saída e armazenamento N/A --bugreport String. Coleta um bugreport completo do dispositivo (valores: always, on-failure).
Android comum Saída e armazenamento --record-video --video String. Quando gravar um vídeo da tela do dispositivo durante a execução do teste. Os valores válidos são always ou on-failure.
Instrumentação do Android Parâmetros e recursos principais --type=instrumentation sessions submit instrumentation A estrutura do subcomando determina o tipo de teste em vez de uma flag --type.
Instrumentação do Android Parâmetros e recursos principais --test --test OBRIGATÓRIO String. Caminho para o APK de teste que contém testes de instrumentação, local ou no Cloud Storage.
Instrumentação do Android Controle de execução e instabilidade --timeout --instrumentation-timeout Duração (por exemplo, 10m, 20s, 1h). Intervalo válido: de 1m a 3h (o padrão é 5m).
Instrumentação do Android Controle de execução e instabilidade 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).
Instrumentação do Android Controle de execução e instabilidade N/A --flaky-test-retry-level String. Define se a nova tentativa será feita no nível de shard ou de test individual (o padrão é shard).
Instrumentação do Android Executor de testes e destinos --test-runner-class --test-runner-class String. A classe totalmente qualificada do executor de testes de instrumentação (por exemplo, com.foo.MyRunner) que será usado. Se não for especificada, uma classe de executor padrão será determinada pelo manifesto do aplicativo.
Instrumentação do Android Executor de testes e destinos --test-targets --test-targets Dicionário de destinos de teste ou filtros de destino a serem executados. Cada destino precisa ser totalmente qualificado com o nome do pacote ou da classe que oferece suporte a chaves como package, notPackage, class, notClass, annotation, notAnnotation e size. Os formatos testfile ou notTestfile não são aceitos.
Instrumentação do Android Executor de testes e destinos --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.
Instrumentação do Android Executor de testes e destinos --environment-variables --additional-test-options Dicionário de opções transmitidas ao executor de testes de instrumentação. Os formatos compatíveis com --test-targets não são permitidos aqui.

Flags específicas do iOS

Use esta tabela para mapear as flags legadas do gcloud firebase test ios run e do Flank para iOS para as novas equivalentes do gcloud alpha device-run sessions submit xctest:

Tipo de teste Grupo de atributos Parâmetro legado (firebase ios / Flank) Parâmetro de DDP desejado Lógica de formato / conversão
iOS comum Parâmetros e recursos principais --additional-ipas --additional-apps Lista de arquivos .ipa auxiliares para instalar no dispositivo antes da execução do teste.
Somente XCTest do iOS Parâmetros e recursos principais --type=xctest sessions submit xctest A estrutura do subcomando determina o tipo de teste em vez de uma flag --type (usa gcloud alpha).
Somente XCTest do iOS Parâmetros e recursos principais --test --test OBRIGATÓRIO String. Caminho para o arquivo ZIP que contém o app iOS e os arquivos XCTest, local ou no Cloud Storage.
Somente XCTest do iOS Controle de execução e instabilidade --timeout --xctest-timeout Duração (por exemplo, 5m, 15m, 1h). Intervalo válido: de 1m a 1h (o padrão é 5m).
Somente XCTest do iOS Saída e armazenamento --record-video --video Quando gravar vídeo: always ou on-failure. Um vídeo é gravado para cada caso de teste UI (iOS 17 ou mais recente).
Somente XCTest do iOS Executor de testes e destinos --xctestrun-file --xctestrun-file String. Caminho para um arquivo .xctestrun personalizado, local ou no Cloud Storage.
Somente XCTest do iOS Executor de testes e destinos --xcode-version --xcode-version String. 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.

Feedback e dúvidas

Entre em contato conosco para registrar bugs e solicitações de recursos ou participe do nosso fórum de discussão.