Iniciar testes com a CLI gcloud

Veja neste guia como executar um teste de instrumentação, Robo ou loop de jogo usando a CLI gcloud.

Para ver uma lista completa dos comandos gcloud que podem ser usados com seu app Android no Test Lab, acesse a documentação de referência para gcloud firebase test android.

Antes de começar

Adicione o Firebase ao seu projeto para Android, caso ainda não tenha feito isso.

Etapa 1. Configurar a CLI gcloud

1. Faça o download do SDK do Google Cloud.

Isso inclui a ferramenta CLI gcloud.

2. Verifique se a instalação está atualizada:

   gcloud components update
   

3. Faça login na CLI gcloud usando sua Conta do Google:
4. Defina seu projeto do Firebase na gcloud, em que PROJECT_ID é o ID do projeto do Firebase:

   gcloud config set project PROJECT_ID
   

Etapa 2. Verificar os dispositivos de teste disponíveis

Use os seguintes comandos a gcloud para visualizar os dispositivos e as localidades de teste que estão disponíveis para o teste.

Como opção, você também pode fazer o download do app Notepad de exemplo para começar a executar os comandos imediatamente. Use o arquivo binário app-debug-unaligned.apk e o arquivo de testes de instrumentação app-debug-test-unaligned.apk, que estão localizados em NotePad/app/build/outputs/apk/.

• models list: receba uma lista atual dos dispositivos Android disponíveis para teste.

  gcloud firebase test android models list
  

  Na resposta ao comando:

  • A coluna MODEL_ID contém o identificador que você pode usar mais tarde para executar testes no modelo do dispositivo.
  • A coluna OS_VERSION_ID contém as versões do sistema operacional compatíveis com o dispositivo.

  Exemplo de saída

  

• models describe: veja mais informações sobre um MODEL_ID específico do Android.

  gcloud firebase test android models describe MODEL_ID
  

  A saída contém a marca, o fabricante, as versões do SO, os níveis de API suportados, as interfaces binárias do aplicativo (ABIs) disponíveis, as datas de lançamento e se o dispositivo é físico ou virtual.

• versions list: acesse uma lista das versões de SO disponíveis no momento para fazer testes.

  gcloud firebase test android versions list
  

  É possível usar um identificador de uma das duas primeiras colunas de resposta ao comando (OS_VERSION_ID e VERSION), para executar testes posteriormente em uma versão do SO Android. Caso você não especifique em quais versões de SO Android o teste será realizado, o padrão usado será o indicado na coluna TAGS.

  Exemplo de saída

  

• locales list: veja a lista atual de localidades disponíveis para teste.

  gcloud firebase test android versions list
  

  A primeira coluna da saída do comando, LOCALE, contém o identificador que você pode usar mais tarde para executar testes de localidade. Se você não especificar as localidades para teste, a localidade padrão utilizada será inglês.

Etapa 3. Executar o teste

Agora que você conhece a variedade de modelos de dispositivos, localidades e versões do SO disponíveis para testar o app, é possível especificar dispositivos usando o comando gcloud firebase test android run e a flag --device para executar testes Robo ou de instrumentação.

Observação: a sinalização --device agora é a maneira mais comum de especificar dispositivos de teste e não pode ser usada com --devices-ids, --os-version-ids, --locales ou --orientations. Para saber mais sobre essas flags legadas, consulte a lista de flags de dimensão de dispositivos obsoletos em gcloud firebase test android run.

Executar um Teste Robo

Mesmo que você não tenha testes de instrumentação, ainda poderá procurar bugs no seu app. Use o Teste Robo para realizar uma revisão automática da interface de usuário do seu app. O Teste Robo ativa o app executando uma análise estática dos vários caminhos por meio da interface de usuário dele e, em seguida, rastreando o app para encontrar falhas e outros problemas em potencial.

Para fazer um Teste Robo, execute o seguinte comando de exemplo:

gcloud firebase test android run \
  --type robo \
  --app app-debug-unaligned.apk \
  --device model=Nexus6,version=21,locale=en,orientation=portrait  \
  --device model=Nexus7,version=19,locale=fr,orientation=landscape \
  --timeout 90s \
  --client-details matrixLabel="Example matrix label"

• O parâmetro --type robo estará implícito se nenhum valor --type for especificado.
• Para ajudar a identificar e localizar as matrizes de teste no Console do Firebase, adicione a flag --client-details matrixLabel="Example matrix label" opcional para rotular a matriz de teste.
• Para ver o conjunto completo de opções de linha de comando para executar testes, digite: gcloud help firebase test android run.

Outra opção para especificar todos esses argumentos na linha de comando é defini-los em um arquivo de argumentos com formatação YAML. Execute gcloud topic arg-files para aprender a usar esse recurso.

Consulte Analisar os resultados do teste para saber como examinar os resultados.

Executar um teste de instrumentação

Agora use a ferramenta de linha de comando gcloud para executar os testes Espresso do app Notepad nas configurações especificadas do dispositivo Android. Use o tipo de teste instrumentation para executar os testes em app-debug-test-unaligned.apk conforme mostrado a seguir:

gcloud firebase test android run \
  --type instrumentation \
  --app app-debug-unaligned.apk \
  --test app-debug-test-unaligned.apk \
  --device model=Nexus6,version=21,locale=en,orientation=portrait  \
  --device model=Nexus7,version=19,locale=fr,orientation=landscape
  --client-details matrixLabel="Example matrix label"

• O parâmetro de instrumentação --type será implícito se um APK de teste for especificado com --test.
• Para ajudar a identificar e localizar as matrizes de teste no Console do Firebase, adicione a flag --client-details matrixLabel="Example matrix label" opcional para rotular a matriz de teste.
• Para conferir o conjunto completo de opções de linha de comando para executar testes, digite gcloud help firebase test android run.

Outra opção para especificar todos esses argumentos na linha de comando é defini-los em um arquivo de argumentos com formatação YAML. Execute gcloud topic arg-files para aprender a usar esse recurso.

A CLI gcloud tem suporte ao Android Test Orchestrator. Para usar o Orquestrador, é preciso ter o AndroidJUnitRunner v1.1 ou versões mais recentes. Para ativar essa ferramenta, use gcloud firebase test android run com a sinalização
--use-orchestrator. Para desativá-la, use a flag --no-use-orchestrator.

Observação: para não gastar sua cota ou receber cobranças por testes com falha, execute o Orchestrator na máquina local antes de usar o Test Lab. Antes de fazer upload do APK, execute um teste na sua própria máquina para confirmar se o Orchestrator está funcionando no seu app. Fazer testes com o Orchestrator é um pouco mais demorado do que o normal e pode afetar o faturamento ou fazer com que os testes excedam o tempo limite.

Para controlar como os testes de instrumentação são executados no Test Lab, você tem a opção de usar outras flags que não são mostradas acima. Por exemplo, é possível usar a sinalização --test-targets para testar uma única classe ou método de classe usado pelo APK de teste. Também é possível descobrir se o teste que falhou estava realmente instável usando a sinalização --num-flaky-test-attempts, que especifica o número de vezes que é necessário repetir a execução de um teste quando um ou mais casos de testes falham por algum motivo. Para saber mais, consulte gcloud firebase test android run.

Relatórios de cobertura de código para testes de instrumentação

O Test Lab é compatível com as ferramentas de relatórios de cobertura de código EMMA e JaCoCo. Se você tiver uma ferramenta integrada ao build do app, poderá gerar um relatório de cobertura de código para testes do Test Lab executando gcloud firebase test android run com alguns argumentos adicionais. Se o Android Test Orchestrator não estiver ativado, use a opção a seguir:

gcloud firebase test android run \
  --type instrumentation \
  --app your-app.apk \
  --test your-app-test.apk \
  --device model=TestDevice,version=AndroidVersion  \
  --environment-variables coverage=true,coverageFile="/sdcard/Download/coverage.ec" \
  --directories-to-pull /sdcard/Download

Se você estiver gerando relatórios de cobertura de código enquanto usa o Android Test Orchestrator, modifique as variáveis de ambiente conforme mostrado a seguir:

gcloud firebase test android run \
  --type instrumentation \
  --app your-app.apk \
  --test your-app-test.apk \
  --device model=TestDevice,version=AndroidVersion  \
  --environment-variables clearPackageData=true,coverage=true,coverageFilePath="/sdcard/Download/" \
  --directories-to-pull /sdcard/Download

Quando o Test Lab terminar de executar seus testes, veja seus relatórios de cobertura de código no Google Cloud Storage:

1. Abra o link do Console do Firebase que a ferramenta gcloud imprimiu acima da tabela de resultados do teste no seu terminal.
2. Clique em uma execução de teste na lista desse link para abrir a respectiva página de detalhes.
3. Clique em Resultados do teste para ver o bucket do Cloud Storage com os resultados do teste dessa execução.
4. Abra artifacts/coverage.ec para ver seu relatório de cobertura de código.

Observação: extrair o diretório sdcard/Download de cada teste coloca todos os arquivos desse diretório no bucket do Cloud Storage. Se você tiver um plano de pagamento Blaze e seu app criar muitos arquivos nesse diretório, a extração desse local pode resultar em cobranças de armazenamento extras.

Analisar os resultados do teste

Após alguns minutos, um resumo básico dos resultados do teste é mostrado na ferramenta gcloud:

A saída da execução do teste de linha de comando também inclui um link para acessar os resultados dele. Para saber mais sobre como interpretar esses resultados, consulte Como analisar resultados do Firebase Test Lab para Android.

Login personalizado e entrada de texto com o teste Robo

O teste Robo preenche automaticamente as telas de login que usam uma Conta do Google para autenticação, a menos que você use o parâmetro --no-auto-google-login. As telas de login personalizadas também são preenchidas com as credenciais da conta de teste fornecidas. Também é possível usar esse parâmetro para fornecer um texto de entrada personalizado a outros campos de texto usados pelo app.

Para preencher os campos de texto no app, use o parâmetro --robo-directives e forneça uma lista separada por vírgulas de pares key-value, em que key é o nome do recurso Android do elemento da IU de destino e value é a string de texto. Também é possível usar essa sinalização para pedir ao Robo para ignorar elementos específicos da IU (por exemplo, o botão "logout"). Os campos EditText são compatíveis, mas não campos de texto em elementos da IU do WebView.

Por exemplo, use o seguinte parâmetro para o login personalizado:

--robo-directives username_resource=username,password_resource=password

Cuidado: somente use credenciais para contas de teste que não estejam associadas a usuários reais.

Comandos e sinalizações disponíveis

A CLI gcloud do Test Lab tem vários comandos e sinalizações disponíveis que permitem executar testes com especificações diferentes:

• Sinalização do Orquestrador de testes do Android: uma sinalização para ativar o Orquestrador, uma ferramenta que permite executar cada um dos testes do app na própria invocação de Instrumentation. O Test Lab sempre executa a versão mais recente do Orquestrador.

• Sinalizações de teste de loop de jogo: um conjunto de sinalizações de configuração que ativam e controlam um "modo de demonstração" para simular ações de jogadores em apps de jogos. Saiba mais sobre como executar testes de loop de jogo com o Test Lab.

• Sinalização de fragmentação uniforme (na versão Beta): uma sinalização que especifica o número de fragmentos em que você quer distribuir os casos de teste de maneira uniforme. Os fragmentos são executados em paralelo em dispositivos separados.

  Observação: os limites para dispositivos físicos são 50, 100 para ARM virtual e 500 para x86 virtual. Isso também se aplica à sinalização de fragmentação manual.

• Sinalização de fragmentação manual (na versão Beta): uma sinalização que especifica um grupo de pacotes, classes e/ou casos de teste a serem executados em um fragmento (um grupo de casos de teste). Os fragmentos são executados em paralelo em dispositivos separados.

• Sinalização de perfis de tráfego de rede (na versão Beta): uma sinalização que especifica qual perfil de rede seus testes usam com dispositivos físicos. Os perfis de rede simulam uma série de condições de redes, permitindo testar o desempenho do app em redes instáveis ou imprevisíveis.

Como escrever scripts de comandos gcloud com o Test Lab

Use scripts de shell ou arquivos em lote para automatizar os testes de apps para dispositivos móveis que seriam executados com a linha de comando gcloud. No exemplo a seguir de script bash, um teste de instrumentação é executado com tempo limite de dois minutos, e o resultado é exibido, informando se o teste teve sucesso.

if gcloud firebase test android run --app my-app.apk --test my-test.apk --timeout 2m
then
    echo "Test matrix successfully finished"
else
    echo "Test matrix exited abnormally with non-zero exit code: " $?
fi

Códigos de saída do script

O Test Lab fornece diversos códigos de saída que podem ser usados para entender melhor os resultados dos testes que você executa usando scripts ou arquivos em lote.

Códigos de saída de script do Test Lab

Código de saída	Observações
0	Todas as execuções de testes foram aprovadas.
1	Ocorreu uma falha geral. As possíveis causas incluem um nome de arquivo que não existe ou um erro de HTTP/rede.
2	O teste foi encerrado porque comandos ou argumentos desconhecidos foram fornecidos.
10	Um ou mais casos de testes (classes ou métodos de classes testados) foram reprovados na execução do teste.
15	Não foi possível determinar no Firebase Test Lab se a matriz de teste foi aprovada ou reprovada devido a um erro inesperado.
18	O ambiente de teste para esta execução de teste não é compatível devido a dimensões de teste incompatíveis. Esse erro poderá ocorrer se o nível da API do Android selecionada não for compatível com o tipo de dispositivo selecionado.
19	A matriz de teste foi cancelada pelo usuário.
20	Ocorreu um erro de infraestrutura de teste.