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 seu Google Cloud projeto ID.

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 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 flag --device várias vezes, como --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 o 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 de forma isolada. 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: a fragmentação de testes pode custar mais. 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.

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 \
    --device 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 comando sessions submit instrumentation, desta forma:

gcloud beta device-run sessions submit instrumentation \
    --test path/to/test.apk \
    --device shiba-34 \
    --device shiba-35 \
    --device 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-max-shard-count: especifica o número máximo de fragmentos a serem criados. O número de dispositivos especificados na flag --device precisa ser menor ou igual a esse valor.

• --smart-sharding-target-duration=SMART_SHARDING_TARGET_DURATION - Especifica o tempo de execução segmentado (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 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

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

A seguir

Em seguida, encontre e analise os registros.