Device Run da Developer Device Platform para executáveis 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 executável independente do Android usando a CLI 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. Preparou um executável independente do Android (como um binário C++ compilado, um executor de comparativo de mercado ou um script de shell).

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

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

Opções para executáveis do Android

• Vários dispositivos: para executar o mesmo executável 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,....
• 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ço em formato separado por vírgulas (por exemplo, --executable-args="--input=a.file,--threads=4"). Para transmitir um argumento que contém 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 do 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 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:

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, 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 executável 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 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 do executável

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

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, e o padrão é 5m.

Etapa 2. Escolher dispositivos

Com a CLI do device-run, os executáveis 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 executável

Envie um executável independente do Android.

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

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 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. Analisar e gerenciar a execução do executável

Para os modos assíncrono e síncrono do comando sessions submit android-executable, 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 da execução e os vincula ao console doGoogle 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 teste de instrumentação do Android ou encontre e analise os registros.