Execução de dispositivo da plataforma para desenvolvedores no 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 .

Para usar essa Google Cloud CLI, você precisa fornecer o ID do projeto 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. criado um projeto do Google Cloud ;
2. Configure a Developer Device Platform seguindo o início rápido.
3. Autenticado com gcloud no terminal.
4. Consulte a visão geral da execução do dispositivo para informações gerais.
5. Criou um teste instrumentado para Android.

Etapa 1. Escolher dispositivos

Usando a CLI device-run, os testes 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 na execução do teste, use o ID correspondente (por exemplo, tegu-35) no comando de envio.

Etapa 2. Executar o teste de instrumentação

Observação: estas flags são necessárias para testes 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, emita um comando semelhante ao seguinte, mas com 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 saída do teste para o link, semelhante a: https://console.cloud.google.com/storage/browser/BUCKET_NAME/automation/sessions/SESSION_ID/.

Etapa 3. Configurar a execução do teste

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

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

• Vários dispositivos: para executar os mesmos testes 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).
• Outros apps: se quiser, especifique um ou mais 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 1h, e o padrão é 5m.
• Bucket personalizado do Cloud Storage: se você não especificar um bucket do Cloud Storage usando a flag --bucket-name=, a Google Cloud CLI usará um bucket padrão chamado PROJECT_ID-devicerun.
• Novas tentativas de teste instável: defina o número máximo de tentativas para executar novamente testes instáveis: --flaky-test-attempts=3 (o padrão é uma tentativa).

Etapa 4. Usar fragmentação

Para incluir a plataforma de dispositivo do desenvolvedor em um fluxo de trabalho de integração e entrega contínuas (CI/CD), considere fragmentar seus testes. A fragmentação de testes divide um conjunto de testes em subgrupos (fragmentos) que são executados separadamente e isolados. A plataforma de dispositivos para desenvolvedores executa automaticamente cada fragmento em paralelo usando vários dispositivos e conclui todo o conjunto de testes em menos tempo.

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

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

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

A plataforma de dispositivos para desenvolvedores é compatível com o sharding inteligente e uniforme. Ao decidir como fragmentar seus testes, considere as seguintes opções:

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

• Quando o tempo de execução de diferentes casos de teste varia muito, use o sharding inteligente. A plataforma de dispositivos para desenvolvedores usa o tempo histórico de execução do teste 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 plataforma de dispositivos para desenvolvedores executa muitos fragmentos em paralelo, as execuções de teste podem ser afetadas pela disponibilidade de dispositivos. Por isso, 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 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 dos dois jobs são idênticas, o serviço centraliza a validação, realizando-a apenas uma vez.

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

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 da seguinte maneira:

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ê vai 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 o fragmentação inteligente. Se não for definido ou for definido como 0, serão usados os limites máximos definidos pelo sistema. 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 o fragmentação inteligente. O intervalo válido é de 2 minutos a 1 hora. Obrigatório quando --sharding-option=smart.

• --smart-sharding-record-name=SMART_SHARDING_RECORD_NAME: especifique o nome do arquivo de registro de fragmentação inteligente, sem a extensão. Obrigatório quando --sharding-option=smart. Esse arquivo YAML está localizado no bucket do Cloud Storage Google Cloudespecificado 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 o modo 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 links para eles no 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 contendo a lista de sessões no projeto, semelhante a esta:

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

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

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 seu ID de 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 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.