Execução de dispositivo da plataforma para desenvolvedores no Android

Visualizar

Esse produto ou recurso está sujeito aos "Termos de ofertas 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 ou um executável independente do Android usando a CLI gcloud beta device-run e encontrar os resultados no Google Cloud console. Ele pressupõe que você tenha uma Google Cloud 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ê precisará fornecer o Google Cloud ID do projeto. Consulte gcloud beta device-run para um resumo dos comandos.

Antes de começar

Estas etapas pressupõem que você já:

1. Criou um Google Cloud projeto do Google Cloud.
2. Configurou a Developer Device Platform seguindo o guia de início rápido.
3. Fez a autenticação com gcloud no terminal.
4. Consultou a Device Run overview para informações gerais.
5. Criou um teste instrumentado para Android ou preparou um executável independente do Android (como um binário C++ compilado, um executor de benchmark ou um script de shell).

Etapa 1. Configurar o teste ou a execução do executável

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

Agora que você executou uma sessão, confira algumas opções de configuração:

Opções para testes de instrumentação e executáveis

• Vários dispositivos: para executar o mesmo teste ou executável em vários dispositivos, forneça a flag --device com vários IDs de dispositivos 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 .so bibliotecas compartilhadas) para o dispositivo antes da execução usando --other-files-to-push=SOURCE=DEST,.... SOURCE oferece suporte a 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 (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 testes instáveis: defina o número máximo de tentativas por job ou fragmento para lidar com a instabilidade: --flaky-test-attempts=3 (o padrão é 1 tentativa).
• Ambiente e diagnósticos do dispositivo: configure a orientação do dispositivo (--orientation=portrait ou landscape), a localidade (--locale=en-US), a localização GPS simulada (--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,....

Opções de teste de instrumentação

• Outros apps: opcionalmente, você pode especificar um ou mais arquivos APKs, AABs ou APKS para instalar antes de executar os testes usando a --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).

Opções executáveis do Android

• Argumentos executáveis: transmita argumentos de linha de comando para o executável usando --executable-args=ARG,... como uma lista separada por vírgulas ou repetindo a flag. Cada elemento se torna um argumento. Portanto, reescreva as linhas de comando separadas por espaços em formato separado por vírgulas (por exemplo, --executable-args="--input=a.file,--threads=4"). Para transmitir um argumento que contenha uma vírgula, prefixe o valor com ^SEP^ para especificar um separador diferente (por exemplo, --executable-args="^;^--shape=1,224,224,3;--threads=4").
• Variáveis de ambiente: defina variáveis de ambiente para o processo executável no dispositivo usando --executable-env-vars=KEY=VALUE,... (por exemplo, --executable-env-vars=LD_LIBRARY_PATH=/data/local/tmp/lib).
• Tempo limite executável: limite a duração da execução do executável: --executable-timeout=10m (o intervalo válido é de 1m a 3h e o padrão é 5m, excluindo o tempo de preparação e limpeza do dispositivo).

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 ou executável 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:

Teste de instrumentação do Android

Para um :

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

Executável do Android

gcloud beta device-run sessions submit android-executable \
  --device shiba-35 \
  --executable ./MY_EXECUTABLE \
  --async

Isso retorna um ID de sessão imediatamente. Em seguida, você pode aguardar 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 ou executável em vários dispositivos, forneça a flag --device com vários IDs de dispositivos separados por vírgulas ou com várias flags --device, cada uma especificando um ID de dispositivo diferente.

Teste de instrumentação do Android

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

Executável do Android

gcloud beta device-run sessions submit android-executable \
  --device shiba-34,tokay-36 \
  --executable ./MY_EXECUTABLE

Ou:

gcloud beta device-run sessions submit android-executable \
  --device shiba-34 \
  --device tokay-36 \
  --executable ./MY_EXECUTABLE

Tempo limite de teste e executável

Limite a duração da execução do teste ou executável:

Teste de instrumentação do Android

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

Executável do Android

gcloud beta device-run sessions submit android-executable \
  --device shiba-35 \
  --executable ./MY_EXECUTABLE \
  --executable-timeout=10m

O intervalo válido é de 1m a 3h para execuções do Android 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, é possível usá-las 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

Consulte Ativar o Orchestrator para mais informações.

Ativar o Orchestrator

Para testes de instrumentação, a Developer Device Platform oferece suporte ao Android Test Orchestrator, que permite executar cada um dos testes do seu app na própria invocação de Instrumentation.

Ao usar o Orchestrator, você:

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

• Isola falhas. Se um teste falhar, ele só vai remover a própria instância de Instrumentation. Isso significa que seus outros testes ainda serão executados e vão fornecer resultados completos.

O Android Test Orchestrator está desativado por padrão na Developer Device Platform. Para ativar o Orchestrator e especificar a versão a ser usada durante a execução do teste, transmita a versão selecionada para a --orchestrator-version=ORCHESTRATOR_VERSION flag no seu sessions submit instrumentation comando, 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 sistema do Orchestrator.

Observação: como cada teste do Orchestrator executa a própria instância de Instrumentation, o aumento nos tempos 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.

Etapa 2. Escolher dispositivos

Usando a CLI device-run, os testes e executáveis do Android podem ser executados em dispositivos físicos e virtuais disponíveis. Para conferir 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 ou executável

É possível enviar um APK de teste de instrumentação do Android ou um executável independente do Android.

Executar um teste de instrumentação

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 sessions submit instrumentation comando 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

Executar um executável do Android

Para executar um executável independente (como um binário C++ compilado, um executor de benchmark de machine learning no dispositivo, como o LiteRT, ou um script de shell) diretamente em um dispositivo Android sem empacotá-lo em um APK, use o sessions submit android-executable comando.

Estas flags são necessárias para executáveis do Android:

• Dispositivo: especifique um dispositivo usando --device: --device shiba-35
• Executável: especifique o caminho local ou do Cloud Storage para o executável usando --executable: --executable /path/to/my_executable

Para executar o executável, emita um comando semelhante ao seguinte, usando seus próprios IDs de dispositivo e caminho executável:

gcloud beta device-run sessions submit android-executable \
  --device shiba-34 \
  --executable /path/to/my_executable \
  --executable-args="--input=/data/local/tmp/file.name,--threads=4" \
  --other-files-to-push=/path/to/model.tflite=/data/local/tmp/model.tflite \
  --paths-to-pull=/data/local/tmp/output

A pasta de relatório de resultados do job pode ser encontrada em um caminho do Cloud Storage, como gs://BUCKET_NAME/automation/sessions/SESSION_ID/. Consulte 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 e entrega contínuas (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. 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 de teste for longo, considere usar a fragmentação.

A Developer Device Platform oferece suporte à 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 n fragmentos.

• Quando o tempo de execução de diferentes casos de teste varia muito, use a fragmentação inteligente. A Developer Device Platform usa o tempo de execução do teste histórico para criar diferentes fragmentos 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 gargalos na 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 os testes com 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ê 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-as apenas uma vez.

Os dois jobs serão listados separadamente na saída final do comando quando concluídos:

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

Fragmentação inteligente

Para fragmentar os testes com 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

Você verá a saída final indicando 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 estiver definido ou 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 - Especifica 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. Necessá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. Necessário quando --sharding-option=smart. Esse arquivo YAML está localizado no Google Cloud bucket de armazenamento especificado por --bucket-name no smart-sharding/ diretório. 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 o modo assíncrono e síncrono dos comandos sessions submit instrumentation e sessions submit android-executable, você pode usar 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 links para os resultados no Google Cloud console. 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 contendo 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 de lista sessions oferece suporte a todas as opções de flag padrão da Google Cloud CLI. Exemplo:

gcloud beta device-run sessions list --limit 5

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

Supondo que você tenha sessões em execução, os resultados serão semelhantes a:

SESSION_ID        START_TIME  STATE
session-d7ff8b81              RUNNING

Caso contrário, você 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 só é marcada para ser cancelada. O cancelamento acontece de forma assíncrona no back-end.

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

A seguir

Em seguida, encontre e analise os registros.