Device Run da Developer Device Platform para instrumentação do Android

Visualizar

Este produto ou recurso está sujeito aos Termos das Soluções Pré-GA na seção Termos Gerais de Serviço dos Termos Específicos de Serviço. Os produtos e recursos pré-GA estão disponíveis "no estado em que se encontram" e podem ter suporte limitado. Para mais informações, consulte as descrições da fase de lançamento.

Neste guia, descrevemos como executar um teste de instrumentação do Android usando a CLI do gcloud beta device-run e encontrar os resultados no console do Google Cloud . Ele pressupõe que você tenha uma conta e um projeto do Google Cloud .

Se você estiver migrando do Firebase Test Lab para a Developer Device Platform, consulte nosso guia de migração, a tradução de comandos e flags e a habilidade de migração para agentes de IA.

Para usar essa Google Cloud CLI, você precisa fornecer o ID do projeto do Google Cloud . Consulte gcloud beta device-run para ver um resumo dos comandos.

Antes de começar

Estas etapas pressupõem que você já:

1. Criou um projeto do Google Cloud .
2. Configure a Developer Device Platform seguindo o Guia de início rápido.
3. Autenticado com gcloud no terminal.
4. Analisou a visão geral do Device Run para informações gerais.
5. Criou um teste de instrumentação para Android.

Etapa 1. Configurar a execução do teste

Dica: para ver todas as opções disponíveis para os comandos submit, execute gcloud beta device-run sessions submit instrumentation --help.

Opções para testes de instrumentação do Android

• Vários dispositivos: para executar o mesmo teste em vários dispositivos, forneça a flag --device com vários IDs de dispositivo separados por vírgulas, como --device shiba-34,tokay-36, ou com várias flags --device, cada uma especificando um ID de dispositivo diferente (por exemplo, --device shiba-34 --device tokay-36).
• Enviar arquivos para o dispositivo: envie outros arquivos (como pesos de modelo de ML, entradas de teste ou bibliotecas compartilhadas .so) para o dispositivo antes da execução usando --other-files-to-push=SOURCE=DEST,.... SOURCE é compatível com caminhos locais e do Cloud Storage (gs://...), e DEST é o caminho de destino no dispositivo.
• Extrair arquivos do dispositivo: extraia arquivos ou diretórios gerados do dispositivo após a conclusão da execução usando --paths-to-pull=DEVICE_PATH,....
• Bucket personalizado do Cloud Storage: especifique um nome de bucket do Cloud Storage existente (sem um esquema ou caminho gs://) usando --bucket-name=. Se você não especificar um bucket, a Google Cloud CLI vai usar ou criar um bucket padrão chamado PROJECT_ID-devicerun.
• Novas tentativas de teste instável: defina o número máximo de tentativas por job ou fragmento para lidar com instabilidade: --flaky-test-attempts=3 (o padrão é 1 tentativa).
• Ambiente e diagnóstico do dispositivo: configure a orientação do dispositivo (--orientation=portrait ou landscape), a localidade (--locale=en-US), o local fictício do GPS (--coordinates=LATITUDE,LONGITUDE), a gravação de vídeo da tela (--video=always ou on-failure), a coleta de dumpsys (--dumpsys=always ou on-failure) ou a coleta de bugreport (--bugreport=always ou on-failure).
• Rótulos: anexe rótulos de chave-valor definidos pelo usuário à sessão usando --labels=KEY=VALUE,....
• Apps adicionais: é possível especificar um ou mais arquivos APK, AAB ou APKS para instalar antes de executar os testes usando a flag --apps=path1,path2,...,path_n. A ordem especificada é a ordem em que esses apps são instalados.
• Tempo limite do teste: limite a duração da execução: --instrumentation-timeout=10m (o intervalo válido é de 1m a 3h, e o padrão é 5m).

Execuções síncronas e assíncronas

Por padrão, o comando de envio é bloqueador (síncrono). Ele vai aguardar a conclusão do teste e imprimir uma tabela de resumo dos resultados.

Para enviar a sessão e retornar imediatamente após o upload de arquivos para o Cloud Storage, adicione a flag --async:

gcloud beta device-run sessions submit instrumentation \
  --device shiba-35 \
  --test ./ANDROID_TESTS.apk \
  --async

Isso retorna um ID de sessão imediatamente. Em seguida, aguarde usando o comando sessions wait:

gcloud beta device-run sessions wait SESSION_ID

O comando será bloqueado até que o job seja concluído.

Vários dispositivos

Para executar o mesmo teste em vários dispositivos, forneça a flag --device com vários IDs de dispositivo separados por vírgulas ou com várias flags --device, cada uma especificando um ID de dispositivo diferente:

gcloud beta device-run sessions submit instrumentation \
  --device shiba-34,tokay-36 \
  --test ./ANDROID_TESTS.apk

Ou:

gcloud beta device-run sessions submit instrumentation \
  --device shiba-34 \
  --device tokay-36 \
  --test ./ANDROID_TESTS.apk

Testar tempo limite

Limite a duração da execução do teste:

gcloud beta device-run sessions submit instrumentation \
  --device shiba-35 \
  --test ./ANDROID_TESTS.apk \
  --instrumentation-timeout=10m

O intervalo válido é de 1m a 3h, e o padrão é 5m.

Versões de software

Descubra e use pacotes de software e versões disponíveis do AndroidX Test Orchestrator e inspecione os ciclos de vida, as versões compatíveis e os metadados antes de configurar as execuções de teste.

Primeiro, liste todos os pacotes de software disponíveis e as versões deles:

gcloud beta device-run software-versions list

Recebendo uma saída semelhante a:

ID                                NAME                              SOFTWARE_TYPE               VERSION  STATE   IS_DEFAULT
androidx-test-orchestrator-1-4-1  AndroidX Test Orchestrator 1.4.1  ANDROIDX_TEST_ORCHESTRATOR  1.4.1    ACTIVE  True
androidx-test-orchestrator-1-6-1  AndroidX Test Orchestrator 1.6.1  ANDROIDX_TEST_ORCHESTRATOR  1.6.1    ACTIVE
xcode-16-4                        Xcode 16.4                        XCODE                       16.4     ACTIVE
xcode-26-2                        Xcode 26.2                        XCODE                       26.2     ACTIVE  True

Em seguida, descreva um pacote específico usando o ID de recurso exato da lista:

gcloud beta device-run software-versions describe androidx-test-orchestrator-1-4-1

Recebendo uma saída semelhante a:

id: androidx-test-orchestrator-1-4-1
isDefault: true
lifecycle:
  state: ACTIVE
name: AndroidX Test Orchestrator 1.4.1
softwareType: ANDROIDX_TEST_ORCHESTRATOR
version: 1.4.1

Agora que você sabe quais versões de software estão disponíveis, use-as nas execuções de teste com a flag --orchestrator-version, desta forma:

gcloud beta device-run sessions submit instrumentation \
  --device shiba-35 \
  --test ./ANDROID_TESTS.apk \
  --orchestrator-version=1.4.1

Ativar o Orchestrator

A Developer Device Platform é compatível com o Android Test Orchestrator, que permite executar cada um dos testes do app na própria invocação de Instrumentation.

Ao usar o Orchestrator, você:

• Evite o estado compartilhado. Cada teste é executado em uma instância própria de Instrumentation. Portanto, se os testes compartilharem o estado do app, a maior parte desse estado será removida da CPU ou da memória do dispositivo após cada teste. Para remover todo o estado compartilhado da CPU e da memória do dispositivo após cada teste, inclua a configuração clearPackageData desta forma: --additional-test-options clearPackageData=true

• Isolar falhas. Se um teste falhar, ele vai remover apenas a própria instância de Instrumentation. Isso significa que os outros testes ainda são executados e fornecem resultados completos.

O Android Test Orchestrator fica desativado por padrão na Developer Device Platform. Para ativar o Orchestrator e especificar a versão dele que será usada durante a execução do teste, transmita a versão selecionada para a flag --orchestrator-version=ORCHESTRATOR_VERSION no comando sessions submit instrumentation, desta forma:

gcloud beta device-run sessions submit instrumentation \
  --device shiba-35 \
  --test ./ANDROID_TESTS.apk \
  --orchestrator-version=1.4.1

Defina a flag como auto para usar a versão padrão do Orchestrator do sistema.

Observação: como cada teste do Orchestrator executa a própria instância de Instrumentation, o aumento no tempo de execução pode aumentar o uso da cota ou o período faturado e fazer com que você exceda os tempos limite dos dispositivos. Talvez seja necessário aumentar a configuração de tempo limite de instrumentação com a flag --instrumentation-timeout conforme necessário.

Etapa 2. Escolher dispositivos

Com a CLI device-run, os testes do Android podem ser executados em dispositivos físicos e virtuais disponíveis. Para ver a lista completa de dispositivos disponíveis, acesse o Catálogo de dispositivos interativo ou execute:

gcloud beta device-run devices list

Exemplo de saída:

ID        MAKE    NAME     MODEL FORM      OS_VERSION CAPACITY  AVAILABILITY  PRODUCTS
tegu-35   Google  Pixel 9a tegu  PHYSICAL  35         MEDIUM    LOW           Automation, Streaming
tokay-34  Google  Pixel 9  tokay PHYSICAL  34         HIGH      HIGH          Automation, Streaming

Consulte o Catálogo de dispositivos para saber como filtrar essa lista. Para segmentar um dispositivo específico para sua execução, use o ID correspondente (por exemplo, tegu-35) no comando de envio.

Etapa 3. Executar o teste

Envie um APK de teste de instrumentação do Android.

Estas flags são necessárias para testes de instrumentação do Android:

• Dispositivo: especifique um dispositivo usando --device: --device shiba-35.
• Teste: especifique o APK de teste usando --test: --test /path/to/test.apk.

Para executar o teste de instrumentação, emita um comando sessions submit instrumentation semelhante ao seguinte, usando seus próprios IDs de dispositivo e caminho de teste:

gcloud beta device-run sessions submit instrumentation \
  --device shiba-34 \
  --apps /path/to/app.apk \
  --test /path/to/test.apk

A pasta do relatório de resultados do job pode ser encontrada em um caminho do Cloud Storage, como gs://BUCKET_NAME/automation/sessions/SESSION_ID/. Confira a resposta ao comando para o link, semelhante a: https://console.cloud.google.com/storage/browser/BUCKET_NAME/automation/sessions/SESSION_ID/.

Etapa 4. Usar fragmentação

Para incluir testes de instrumentação da Developer Device Platform em um fluxo de trabalho de integração contínua e entrega contínua (CI/CD), considere fragmentar os testes. A fragmentação de testes divide um conjunto de testes de instrumentação em subgrupos (fragmentos) que são executados separadamente e de forma isolada. A Developer Device Platform executa automaticamente cada fragmento em paralelo usando vários dispositivos e conclui todo o conjunto de testes em menos tempo.

Cuidado: fragmentar testes pode elevar os custos. Embora a fragmentação de testes reduza o tempo necessário para executar todos os seus testes, a sobrecarga de iniciar seu aplicativo em cada fragmento pode aumentar o tempo de cada dispositivo.

Etapa 4.1. Como escolher a opção de fragmentação

Se os jobs tiverem apenas um pequeno número de casos de teste ou se o tempo total de execução de todos os casos de teste não for longo, não será necessário usar a fragmentação. Se você tiver um grande número de casos de teste ou se o tempo total de execução de todos os casos for longo, considere usar a fragmentação.

O Developer Device Platform é compatível com fragmentação inteligente e uniforme. Ao decidir como fragmentar os testes, considere as seguintes opções:

• Se todos os casos de teste levarem um tempo semelhante, use a fragmentação uniforme dividindo todos os casos de teste em fragmentos n.

• Quando o tempo de execução de diferentes casos de teste varia muito, use a fragmentação inteligente. Developer Device Platform usa o tempo histórico de execução do teste para criar fragmentos diferentes e tenta concluir todos os fragmentos em uma duração semelhante.

Observação: o número de fragmentos é configurável. Portanto, quando a Developer Device Platform executa muitos fragmentos em paralelo, as execuções de teste podem ser limitadas pela disponibilidade de dispositivos. Por esse motivo, recomendamos que o número de dispositivos especificado na flag --device seja menor ou igual ao número de fragmentos.

Fragmentação uniforme

Para fragmentar seus testes com a fragmentação uniforme, inclua as flags --sharding-option=uniform e --uniform-sharding-count= no comando sessions submit instrumentation desta forma:

gcloud beta device-run sessions submit instrumentation \
    --test path/to/test.apk \
 --device shiba-34,tokay-36 \
    --sharding-option=uniform \
    --uniform-sharding-count=2

Você vai ver uma saída indicando Job status: 2 running. O serviço cria dois jobs, um para cada dispositivo. Como as entradas para os dois jobs são idênticas, o serviço centraliza a validação, realizando-a apenas uma vez.

Você vai ver os dois jobs listados separadamente na saída final do comando quando ele for concluído:

JOB NAME  EXECUTION NAME  EXECUTION RESULT
job-000   execution-000   PASSED
job-001   execution-000   PASSED

Fragmentação inteligente

Para fragmentar seus testes com a fragmentação inteligente, inclua as flags --sharding-option=smart, --smart-sharding-max-shard-count=, --smart-sharding-target-duration= (em minutos ou 1h) e --smart-sharding-record-name= no comando sessions submit instrumentation desta forma:

gcloud beta device-run sessions submit instrumentation \
    --test path/to/test.apk \
    --device shiba-34,shiba-35,tokay-36 \
    --sharding-option=smart \
    --smart-sharding-max-shard-count=3 \
    --smart-sharding-target-duration=5m \
    --smart-sharding-record-name=test.yaml

A saída final vai indicar que três jobs foram executados:

Session [session-3cd0564a] finished with result [ERROR].
JOB NAME  EXECUTION NAME  EXECUTION RESULT
job-000   execution-000   PASSED
job-001   execution-000   PASSED
job-002   execution-000   PASSED

Confira um resumo das flags de fragmentação inteligente usadas aqui:

• --smart-sharding-max-shard-count=SMART_SHARDING_MAX_SHARD_COUNT: especifique o número máximo de fragmentos a serem criados para a fragmentação inteligente. Se não for definido ou se for definido como 0, os limites máximos definidos pelo sistema serão usados. O intervalo válido é de 0 a 20 para dispositivos físicos e de 0 a 200 para dispositivos virtuais.

• --smart-sharding-target-duration=SMART_SHARDING_TARGET_DURATION: especifique o tempo de execução desejado (por exemplo, 2m, 10m, 1h) por fragmento para a fragmentação inteligente. O intervalo válido é de 2m a 1h. Obrigatório quando --sharding-option=smart.

• --smart-sharding-record-name=SMART_SHARDING_RECORD_NAME: especifica o nome do arquivo de registro de fragmentação inteligente, excluindo a extensão de arquivo. Obrigatório quando --sharding-option=smart. Esse arquivo YAML está localizado no bucket do Storage do Google Cloud especificado por --bucket-name no diretório smart-sharding/. Se o arquivo não existir, ele será criado automaticamente. Caso contrário, o conteúdo será atualizado após a conclusão da sessão.

Etapa 5. Analisar e gerenciar a execução do teste

Para os modos assíncrono e síncrono do comando sessions submit instrumentation, use o comando sessions describe para consultar o status do job durante a execução ou receber o resultado após a conclusão:

gcloud beta device-run sessions describe SESSION_ID

A saída resume os resultados do teste e os vincula ao console do Google Cloud . Exemplo:

Session SESSION_ID finished with result [FAILED].
Result files are stored at [https://console.cloud.google.com/storage/browser/BUCKET_NAME/automation/sessions/SESSION_ID/].
JOB NAME  EXECUTION NAME  EXECUTION RESULT
job-000   all             FAILED: 2 test cases failed, 5 passed

Use o comando a seguir para listar todas as sessões em execução e concluídas:

gcloud beta device-run sessions list

Receba uma saída com a lista de sessões no seu projeto, semelhante a:

SESSION_ID                                    START_TIME                STATE
session-4825e153                              2026-07-28T16:38:43.155Z  DONE
session-813ca602                              2026-07-28T22:40:32.415Z  DONE
session-67cd0570                              2026-07-16T08:25:55.474Z  DONE
session-17cc299c                              2026-07-14T14:31:33.649Z  DONE
session-911d0763                              2026-07-09T00:39:02.051Z  DONE
session-4e943fea                              2026-07-15T23:08:32.252Z  DONE
session-0132e458                              2026-08-20T18:33:19.751Z  DONE
session-1077f07b                              2026-07-28T22:35:43.848Z  DONE
session-71b054c6                              2026-07-15T01:15:41.643Z  DONE
session-4f8b2e45                              2026-08-06T23:11:56.161Z  DONE

O comando sessions list é compatível com todas as opções de flag padrão da Google Cloud CLI. Exemplo:

gcloud beta device-run sessions list --limit 5

O que resulta em resultados semelhantes a:

SESSION_ID                            START_TIME                STATE
session-4825e153                      2026-07-28T16:38:43.155Z  DONE
session-813ca602                      2026-07-28T22:40:32.415Z  DONE
93ec2df2-d5bf-4c36-b7f7-c2a4fb0dc3ce  2026-07-03T05:10:58.015Z  DONE
session-67cd0570                      2026-07-16T08:25:55.474Z  DONE
session-17cc299c                      2026-07-14T14:31:33.649Z  DONE

Ou, para encontrar todas as sessões em execução, execute:

gcloud beta device-run sessions list --filter RUNNING

Se você tiver sessões em execução, os resultados serão semelhantes a:

SESSION_ID        START_TIME  STATE
session-d7ff8b81              RUNNING

Caso contrário, você vai receber Listed 0 items.

Para cancelar uma sessão em execução, execute este comando com o ID da sessão:

gcloud beta device-run sessions cancel SESSION_ID

O comando retorna imediatamente, já que a sessão é apenas marcada para cancelamento. O cancelamento acontece de forma assíncrona no back-end.

Se a sessão já tiver sido concluída, apenas o status atual será impresso. Solicitar o cancelamento de uma sessão concluída não é um erro.

A seguir

Em seguida, execute um executável do Android ou encontre e analise registros.