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 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:

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")
```
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 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:

Crie ou recrie o aplicativo principal e o pacote de teste.
Instale o pacote de teste e os principais arquivos do pacote do aplicativo Android (arquivos APK) no dispositivo ou emulador Android atual.
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)	Mostra 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 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 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çẽ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`	<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>`	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 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.