Iniciar testes com a CLI do gcloud

O Firebase Test Lab oferece infraestrutura baseada em nuvem para testar apps para Android, incluindo integração completa com a interface de linha de comando (CLI, na sigla em inglês) gcloud. Este documento aborda a instalação e a configuração necessárias para começar a usar o Test Lab a partir da CLI da gcloud.

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

Criar um projeto do Firebase

Se você não tiver um projeto do Firebase para o app, acesse o Console do Firebase e clique em Criar novo projeto para fazer isso agora mesmo. Você precisa ser o proprietário ou ter permissões de edição no projeto.

É possível fazer um número limitado de execuções diárias de teste no Test Lab no plano Spark. Para usar o Test Lab sem limites diários de cota, faça upgrade para o plano Firebase Blaze.

Configurar a CLI gcloud

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

Isso inclui a ferramenta CLI do gcloud.

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

   gcloud components update
   

3. Faça login na CLI do gcloud usando sua Conta do Google:

   gcloud auth login
   

4. Defina seu projeto do Firebase no gcloud, em que PROJECT_ID é o ID do projeto do Firebase:

   gcloud config set project PROJECT_ID
   

Configurar seu teste

Neste exemplo, você executará alguns testes em um app simples de anotações para Android chamado Notepad.

1. Faça o download do arquivo APK binário para o app Notepad (app-debug-unaligned.apk) e os testes de instrumentação correspondentes dele (app-debug-test-unaligned.apk) disponíveis no diretório NotePad/app/build/outputs/apk/ de notepad.zip.

2. Veja a seguir a lista atual de dispositivos Android disponíveis para teste:

   
   $ gcloud firebase test android models list
   

   A primeira coluna da resposta ao comando, MODEL_ID, contém o identificador que é possível usar mais tarde para executar testes em um modelo específico. A coluna OS_VERSION_ID lista as versões do sistema operacional compatíveis com esse dispositivo. Quando você não especifica os MODEL_ID(s) para fazer o teste, é usado o padrão indicado na coluna TAGS.

3. Saiba mais sobre um MODEL_ID específico do Android com o comando firebase test android models describe, da seguinte maneira:

   
   $ gcloud firebase test android models describe Nexus5
   

   No exemplo de comando mostrado acima, as informações detalhadas sobre o modelo Nexus5 são fornecidas, inclusive a marca, o fabricante e os níveis de API compatíveis e se o modelo é físico ou virtual.

4. Veja a lista atual das versões do SO Android disponíveis para teste:

   
   $ 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 do SO Android o teste será realizado, o padrão usado será o indicado na coluna TAGS.

5. Veja a lista atual de localidades disponíveis para teste:

   
   $ gcloud firebase test android locales 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. A saída do comando não foi incluída aqui porque centenas de localidades estão disponíveis.

Como executar testes

Agora que você conhece a variedade de modelos de dispositivos, versões de SO e localidades disponíveis para testar seu app, use essas informações para especificar dispositivos de teste usando o comando gcloud firebase test android run e a sinalização --device. Esse comando e essa sinalização são usados tanto no teste automático do app pelo Robo quanto na execução dos testes de instrumentação criados especificamente para testar o app.

Como executar o 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 do 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 localizar falhas e outros possíveis problemas.

Começaremos executando um 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

O parâmetro --type robo estará implícito se nenhum valor --type for especificado. 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 saber como usar esse recurso.

Consulte a seção Analisar resultados de teste para saber como investigar os resultados com base no teste Robo.

Como executar testes de instrumentação

Agora, use a ferramenta de linha de comando gcloud para executar os testes Espresso do app Notepad nas configurações do dispositivo Android especificadas, usando o tipo de teste instrumentation para executar os testes no app-debug-test-unaligned.apk da seguinte maneira:

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

O parâmetro --type instrumentation estará implícito se um APK de teste tiver sido especificado com --test. 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 saber como usar esse recurso.

A CLI do gcloud é compatível com o Orquestrador de testes do Android. Para usar o Orquestrador, é preciso ter o AndroidJUnitRunner v1.0 ou posterior. Para ativá-lo, use gcloud firebase test android run com a sinalização
--use-orchestrator. Para desativá-lo, use a sinalização --no-use-orchestrator.

Observação: você tem a opção de controlar como os testes de instrumentação são executados no Test Lab usando sinalizações adicionais que não são mostradas acima. Por exemplo, é possível usar a sinalização --test-targets para testar uma única classe ou um método de classe usado pelo APK de teste. Também é possível descobrir se o teste que falhou foi realmente instável ou não usando a sinalização "--num-flaky-test-attempts", que especifica o número de vezes que uma execução de teste deve ser repetida se um ou mais casos de teste falharem por qualquer 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 à compilação do seu app, poderá gerar um relatório de cobertura de código para testes do Test Lab executando o comando gcloud firebase test android run com os seguintes argumentos:

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/coverage.ec" \
  --directories-to-pull /sdcard

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 intervalo do Google 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.

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 ver os resultados do teste. 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 conclui 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

Comandos e sinalizações disponíveis

A CLI da 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 Orquestrador, uma ferramenta que permite executar cada um dos testes do aplicativo 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 do jogador em aplicativos 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 uniformemente os casos de teste. Os fragmentos são executados em paralelo em dispositivos separados.

• Sinalização manual de fragmentação (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.