Execução de dispositivo da plataforma de dispositivo do desenvolvedor

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 usando a gcloud beta device-run CLI e encontrar os resultados no Google Cloud console. Ele pressupõe que você tenha uma Google Cloud conta e um projeto.

Para usar essa Google Cloud CLI, você precisa 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á criou um Google Cloud projeto, concluiu as etapas de configuração na Plataforma de dispositivos para desenvolvedores Início rápido guia e autenticado com gcloud no terminal.

Além disso, você precisa ter um teste de instrumentação do Android pronto para execução. Consulte Criar testes instrumentados paraorientações.

Além disso, você precisa ter identificado os IDs dos dispositivos em que quer executar suas cargas de trabalho. Consulte o catálogo de dispositivos para instruções.

Dica: anexe --help a qualquer comando gcloud para conferir informações detalhadas sobre o uso.

Executar um teste

Agora que você conhece os IDs dos dispositivos disponíveis para testar seu app, é possível especificar dispositivos usando o gcloud beta device-run sessions submit instrumentation comando e a --device flag para executar testes de instrumentação.

**Dica**: para conferir todas as flags disponíveis, execute gcloud beta device-run sessions submit instrumentation --help.

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://<your_project_id>/automation/sessions/session-id/. Consulte a saída do teste para o link, semelhante a: https://console.cloud.google.com/storage/browser/your_project_id/automation/sessions/session-id/.

Configurar a execução do teste

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

• Para executar os mesmos testes em vários dispositivos, forneça a --device flag 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).
• Opcionalmente, é possível especificar 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.
• Você precisa especificar o APK de teste com a flag --test.
• Quando você especifica um caminho local com as flags --apps ou --test, a CLI do Google Cloud copia automaticamente para o bucket do Cloud Storage em gs://my-project-id/automation/inputs/date_time_four_chars_suffix/ sempre que você executa o comando.
• Como o upload de APKs grandes pode demorar, você pode referenciar diretamente seus APKs usando os caminhos gs:// do Cloud Storage para economizar tempo de upload.

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

O comando sessions submit instrumentation bloqueia os resultados da sessão por padrão, o que significa que ele vai aguardar a conclusão da execução do teste e gerar resultados semelhantes a:

Using the default Cloud Storage bucket [gs://<my-project-id>] for input and result files. Will create the bucket if it does not exist.
Uploading [app.apk].
Uploading [test.apk].

Initiated long-running operation [operation-number] to create session.
Creating session [session-id] in location [global].
Result files will be stored at [https://console.cloud.google.com/storage/browser/<my-project-id>/automation/sessions/session-id/].
Waiting for session [session-id] to complete....done.

Session [session-id] finished with result [FAILED].
JOB NAME  EXECUTION NAME  EXECUTION RESULT
job-000   all             FAILED: 2 test cases failed, 5 passed

Para executar o comando de forma assíncrona, inclua a flag --async. Isso permite que o comando seja encerrado imediatamente após o upload de arquivos para o Cloud Storage e a impressão do ID da operação e do ID da sessão. Você pode usar o comando de espera de operações e o ID da operação para aguardar a execução. Ele será bloqueado até que o job seja concluído:

gcloud beta device-run operations wait your_operation_id

Usar a fragmentação

Para incluir a plataforma de dispositivos para desenvolvedores 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.

**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 app em cada fragmento pode aumentar o tempo de cada dispositivo.

Opções 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 a fragmentação. Se você tiver um grande número de casos de teste ou o tempo total de execução de todos os casos de teste for longo, considere usar a fragmentação.

A plataforma de dispositivos para desenvolvedores oferece suporte à fragmentação 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 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 plataforma de dispositivos para desenvolvedores usa o tempo de execução histórico 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 limitadas pela disponibilidade de dispositivos. Por esse motivo, recomendamos que o número de dispositivos especificados 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ê verá uma saída indicando Job status: 2 running. O serviço cria dois jobs, um para cada dispositivo. Como as entradas para ambos os 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 seus testes com a fragmentação inteligente, inclua as --sharding-option=smart, --smart-sharding-max-shard-count=, --smart-sharding-target-duration= (em minutos ou 1h) e --smart-sharding-record-name= flags no sessions submit instrumentation comando 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 do arquivo. Necessário quando --sharding-option=smart. Esse arquivo YAML está localizado no Google Cloud bucket do Cloud Storage 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.

Conferir e gerenciar a execução do teste

Para o modo assíncrono e síncrono do comando sessions submit instrumentation, 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 do. Exemplo:

Session [session-id] finished with result [FAILED].
Result files are stored at [https://console.cloud.google.com/storage/browser/your_project_id-devicerun/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 do gcloud. 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 your_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.