Testar na linha de comando

Este documento descreve como executar testes direto na linha de comando. Ele pressupõe que você já saiba criar um app Android e programar testes nele. Para mais informações sobre a criação de testes para o app, consulte Testar apps no Android.

Quando você cria o app usando o sistema de build do Gradle, o Plug-in do Android para Gradle permite executar testes no projeto Gradle usando a linha de comando. Para ter um controle mais refinado, você pode executar testes com um shell do Android Debug Bridge (adb). Isso pode ser útil ao executar testes em um ambiente de integração contínua.

Aprenda a executar testes de instrumentação automatizados na linha de comando usando dispositivos virtuais que o Gradle gerencia para você. Consulte Escalonar seus testes com dispositivos gerenciados pelo Gradle.

Executar testes com o Gradle

O Plug-in do Android para Gradle permite executar testes no projeto Gradle usando a linha de comando.

A tabela abaixo oferece um resumo de como executar testes com o Gradle:

Tabela 1. Diferentes maneiras de executar testes com o Gradle.

Tipo de teste de unidade Comando a ser executado Local do resultado do teste
Teste de unidade local Execute a tarefa test: 

./gradlew test
Arquivos de resultado de teste HTML:
diretório path_to_your_project/module_name/build/reports/tests/.

Arquivos de resultados de teste XML:
diretório path_to_your_project/module_name/build/test-results/.

Teste de unidade instrumentado Execute a tarefa connectedAndroidTest: 

./gradlew connectedAndroidTest
Arquivos de resultado de teste HTML:
diretório path_to_your_project/module_name/build/reports/androidTests/connected/.

Arquivos de resultados de teste XML:
diretório path_to_your_project/module_name/build/outputs/androidTest-results/connected/.

O Gradle oferece suporte a abreviações de nomes de tarefas (link em inglês). Por exemplo, você pode iniciar a tarefa connectedAndroidTest inserindo o seguinte comando:

./gradlew cAT

Também é possível executar as tarefas check e connectedCheck do Gradle. Elas executam os testes locais ou de instrumentação, respectivamente, mas incluem outras verificações adicionadas por outros plug-ins do Gradle.

Executar testes em um módulo

As tarefas test e connectedAndroidTest executam testes em cada módulo do projeto. É possível executar testes em um módulo específico prefixando a tarefa test ou connectedAndroidTest com o nome do módulo e dois pontos (:). Por exemplo, o comando a seguir executa testes de instrumentação apenas para o módulo mylibrary:

./gradlew mylibrary:connectedAndroidTest

Executar testes em uma variante de build

As tarefas test e connectedAndroidTest executam testes em cada variante de build do projeto. Você pode especificar uma variante de build usando a sintaxe abaixo.

  • Para testes de unidade locais: 
    ./gradlew testVariantNameUnitTest
  • Para testes instrumentados: 
    ./gradlew connectedVariantNameAndroidTest

Executar métodos ou classes de teste específicos

Ao executar testes de unidade locais, o Gradle permite direcionar testes específicos usando a flag --tests. Por exemplo, o comando abaixo executa apenas os testes sampleTestMethod na variante de build especificada. Para saber mais sobre o uso da sinalização --tests, leia a documentação do Gradle sobre filtragem de testes (em inglês).


./gradlew testVariantNameUnitTest --tests '*.sampleTestMethod'

Executar testes com o adb

Quando você usa o Android Debug Bridge (adb) para testes na linha de comando, existem mais opções para escolher os testes que vão ser executados do que se usasse qualquer outro método. É possível selecionar métodos individuais, filtrar de acordo com anotações personalizadas ou especificar opções de teste. Como a execução de testes é totalmente controlada pela linha de comando, você pode personalizar o teste com scripts de shell de várias maneiras.

Para executar um teste na linha de comando, execute adb shell a fim de iniciar um shell de linha de comando no dispositivo ou emulador. Dentro desse shell, é possível interagir com o gerenciador de atividades usando o comando am e o subcomando instrument para executar os testes.

De maneira mais fácil, você pode iniciar um shell do adb, chamar am instrument e especificar flags de linha de comando em uma única linha de entrada. O shell é aberto no dispositivo ou emulador, executa os testes, gera resultados e, por fim, retorna para a linha de comando no computador.

Para executar um teste com am instrument:

  1. Crie ou recrie o aplicativo principal e o pacote de teste.
  2. Instale o pacote de teste e os principais arquivos do pacote do aplicativo Android (arquivos APK) no dispositivo ou emulador Android atual.

  3. Na linha de comando, digite:

    adb shell am instrument -w <test_package_name>/<runner_class>

    em que <test_package_name> é o nome do pacote Android do aplicativo em teste e <runner_class> é o nome da classe de execução de teste Android usada. O nome do pacote Android é o valor do atributo do pacote do elemento de manifesto no arquivo de manifesto do pacote de teste (AndroidManifest.xml).

    A classe de execução de teste do Android geralmente é AndroidJUnitRunner:

    adb shell am instrument -w com.android.example/androidx.test.runner.AndroidJUnitRunner

Os resultados do teste são exibidos em STDOUT.

Flags de "am instrument"

Para encontrar uma lista de todas as flags a serem usadas com o comando am instrument, execute adb shell am help. Algumas flags importantes são descritas na tabela abaixo:

Tabela 2. Flags am instrument importantes

Flag Valor Descrição
-w (nenhum) Força am instrument a esperar até que a instrumentação termine antes de ser encerrada. Isso mantém o shell aberto até que os testes sejam concluídos. Essa flag é necessária para ver os resultados dos testes.
-r (nenhum) Mostra os resultados no formato bruto. Use essa flag quando quiser coletar medidas de desempenho sem que sejam formatadas como resultados de teste. Ela foi projetada para uso com a flag -e perf true (documentada na seção Opções de "am instrument").
-e <test_options> Oferece opções de teste, como pares de chave-valor. A ferramenta am instrument transmite essas opções para a classe de instrumentação especificada com o método onCreate(). Você pode especificar várias ocorrências de -e <test_options>. As chaves e os valores são descritos na seção Opções de "am instrument". Só é possível usar esses pares de chave-valor com AndroidJUnitRunner ou InstrumentationTestRunner e as subclasses correspondentes. Usar esses pares com qualquer outra classe não gera efeito.
--no-hidden-api-checks (nenhum) Desativa restrições no uso de APIs ocultas. Para mais informações sobre as APIs ocultas e como isso pode afetar seu app, consulte Restrições para interfaces que não são SDK.

Opções de "am instrument"

A ferramenta am instrument transmite opções de teste para AndroidJUnitRunner ou InstrumentationTestRunner na forma de pares de chave-valor, usando a flag -e com a seguinte sintaxe:

-e <key> <value>

Algumas chaves aceitam vários valores. Especifique diversos valores em uma lista separada por vírgulas. Por exemplo, a invocação de AndroidJUnitRunner fornece diversos valores para a chave package:

adb shell am instrument -w -e package com.android.test.package1,com.android.test.package2 \
> com.android.test/androidx.test.runner.AndroidJUnitRunner

A tabela abaixo lista os pares de chave-valor que podem ser usados com o executor de teste.

Tabela 3. Pares de chave-valor da flag -e para usar com o executor de teste.

Tecla Valor Descrição
package <Java_package_name> Nome do pacote Java totalmente qualificado para um dos pacotes no aplicativo em teste. Toda classe de caso de teste que usa esse nome de pacote é executada. Esse não é um nome de pacote Android. Um pacote de teste tem um único nome de pacote Android, mas pode ter vários pacotes Java dentro dele.
class <class_name> Nome da classe Java totalmente qualificada para uma das classes de caso de teste. Somente essa classe de caso de teste é executada.
<class_name>#method name Nome totalmente qualificado da classe de um caso de teste e um dos métodos relacionados. Apenas esse método é executado. Observe a cerquilha (#) entre o nome da classe e o nome do método.
func true Executa todas as classes de teste que estendem InstrumentationTestCase.
unit true Executa todas as classes de teste que não estendem InstrumentationTestCase nem PerformanceTestCase.
size [small | medium | large] Executa um método de teste com anotação por tamanho. As anotações são @SmallTest, @MediumTest e @LargeTest.
perf true Executa todas as classes de teste que implementam PerformanceTestCase. Ao usar essa opção, especifique a flag -r para am instrument. Assim, a saída vai ser mantida no formato bruto em vez de reformatada como resultados de testes.
debug true Executa testes no modo de depuração.
log true Carrega e registra todos os testes especificados, mas não os executa. As informações de teste são mostradas em STDOUT. Use essa opção para verificar combinações de outros filtros e especificações de teste.
emma true Executa uma análise de cobertura de código EMMA e grava a saída em /data/<app_package>/coverage.ec no dispositivo. Para substituir o local do arquivo, use a chave coverageFile descrita na entrada a seguir.

Observação: essa opção exige um build do aplicativo em teste instrumentado por EMMA, que pode ser gerado com o destino coverage.

coverageFile <filename> Substitui o local padrão do arquivo de cobertura EMMA no dispositivo. Especifique esse valor como um caminho e nome de arquivo no formato UNIX. O nome de arquivo padrão é descrito na entrada da chave emma.

Ao usar a flag -e, esteja ciente do seguinte:

  • am instrument invoca onCreate(Bundle) com um Bundle contendo os pares de chave-valor.
  • A chave package tem prioridade sobre a class. Se você especificar um pacote e, em seguida, uma classe nesse pacote, o Android vai executar todos os testes no pacote e ignorar a chave de classe.
  • As chaves func e unit são mutuamente exclusivas.

Exemplos de uso

As seções a seguir mostram exemplos de como usar am instrument para executar testes. Eles são baseados na seguinte estrutura:

  • O pacote de teste tem o nome do pacote Android com.android.demo.app.tests.
  • Há duas classes de testes de instrumentação:
    • TestClass1, que contém o método de teste testMethod1.
    • TestClass2, que contém os métodos de teste testMethod2 e testMethod3.
  • O executor de teste é AndroidJUnitRunner.

Executar todo o pacote de teste

Para executar todas as classes de teste no pacote de teste, digite:

adb shell am instrument -w com.android.demo.app.tests/androidx.test.runner.AndroidJUnitRunner

Executar todos os testes em uma classe de caso de teste

Para executar todos os testes na classe TestClass1, digite:

adb shell am instrument -w  \
> -e class com.android.demo.app.tests.TestClass1 \
> com.android.demo.app.tests/androidx.test.runner.AndroidJUnitRunner

Selecionar um subconjunto de testes

Para executar todos os testes na classe TestClass1 e no método testMethod3 em TestClass2, insira:

adb shell am instrument -w \
> -e class com.android.demo.app.tests.TestClass1,com.android.demo.app.tests.TestClass2#testMethod3 \
> com.android.demo.app.tests/androidx.test.runner.AndroidJUnitRunner

Veja mais casos de uso na referência da API AndroidJUnitRunner.