Testar na linha de comando

Este documento descreve como executar testes direto na linha de comando. Este documento pressupõe que você já saiba criar um app Android e programar testes no app Android. Para ver 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 compilação 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ê também pode executar testes com um shell do Android Debug Bridge (adb).

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). Isso significa, por exemplo, que para iniciar a tarefa connectedAndroidTest, basta digitar este comando:

./gradlew cAT

Também é possível executar as tarefas check e connectedCheck do Gradle. Elas executam os testes locais ou instrumentados, respectivamente, mas incluem também 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. Você pode executar testes apenas para um módulo específico do projeto, prefixando o teste ou tarefa connectedAndroidTest com o nome do módulo e dois pontos (:). Por exemplo, o comando abaixo executa testes instrumentados 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 especificar testes usando a sinalização --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'

Relatórios de vários módulos para testes instrumentados

Conforme descrito na Tabela 1, o Gradle salva os resultados de testes instrumentados no diretório build/ de cada módulo testado. No entanto, ao executar testes em vários módulos, pode ser útil combinar todos os resultados do teste em um único relatório. Para gerar um único relatório durante a execução de testes em vários módulos, siga as etapas abaixo:

  1. No arquivo build.gradle do projeto, adicione este código após o bloco buildscript{}:

    Groovy

    apply plugin 'android-reporting'
    

    Kotlin

    apply(plugin = "android-reporting")
    
  2. Invoque a tarefa test ou connectedAndroidTest usando a tarefa mergeAndroidReports. Exemplo:

    ./gradlew connectedAndroidTest mergeAndroidReports
    

    Se você quiser pular falhas de teste para que o Gradle conclua a execução dos testes restantes, adicione a opção --continue:

    ./gradlew connectedAndroidTest mergeAndroidReports --continue
    

Ao concluir a execução de todos os testes, o Gradle salva os resultados combinados no diretório path_to_your_project/build/.

Executar testes com o adb

Quando você usa o Android Debug Bridge (adb) para executar testes na linha de comando, tem 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 sinalizações 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 (AndroidManifest.xml) do pacote de teste. A classe de execução de teste do Android geralmente é AndroidJUnitRunner.

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

Os resultados do teste são exibidos em STDOUT.

Sinalizações de "am instrument"

Para ver uma lista de todas as sinalizações que podem ser usadas com o comando am instrument, execute adb shell am help. Algumas sinalizações importantes são descritas na tabela abaixo:

Tabela 2. Sinalizações de "am instrument" importantes.

Sinalização Valor Descrição
-w (nenhum) Força am instrument a esperar até que a instrumentação termine antes de ser encerrada. O efeito esperado é manter o shell aberto até que os testes sejam encerrados. Essa sinalização é necessária para ver os resultados dos testes.
-r (nenhum) Exibe os resultados no formato bruto. Use essa sinalização quando quiser coletar medidas de desempenho sem que sejam formatadas como resultados de teste. Essa sinalização foi projetada para uso com a sinalização -e perf true (documentada na seção am instrument options).
-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 valores são descritos na seção am instrument options. 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çẽs no uso de APIs ocultas Para ver 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 sinalização -e com esta 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 abaixo 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/android.support.test.runner.AndroidJUnitRunner

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

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

Chave 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. Quando você usar essa opção, especifique também a sinalização -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> Modifica 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 sinalização -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 instrumentados:
    • Foo1, que contém o método de teste bar1, e
    • Foo2, que contém os métodos de teste bar2 e bar3
  • 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/android.support.test.runner.AndroidJUnitRunner

Executar todos os testes em uma classe de caso de teste

Para executar todos os testes na classe Foo1, digite:

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

Selecionar um subconjunto de testes

Para executar todos os testes na classe Foo1 e no método bar3 no Foo2, digite:

adb shell am instrument -w \
> -e class com.android.demo.app.tests.Foo1,com.android.demo.app.tests.Foo2#bar3 \
> com.android.demo.app.tests/android.support.test.runner.AndroidJUnitRunner

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