Testar na linha de comando

Este documento descreve como criar e executar testes diretamente na linha de comando. Ele pressupõe que você já saiba criar um aplicativo para Android no seu ambiente de programação.

Como executar testes

É possível executar testes na linha de comando com o Gradle ou com um shell do Android Debug Bridge (adb).

O plug-in do Android para o Gradle permite executar testes de unidade no projeto do Gradle pela linha de comando. Para saber mais sobre como criar testes de unidade para o app, consulte Criar testes de unidade eficazes.

Como executar testes de unidade com o Gradle

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

Tipo de teste de unidade	Comando a ser executado	Local do resultado do teste
Teste de unidade local	Chame 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 de instrumentação	Chame 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 é compatível com abreviações de nomes de tarefas. Isso significa, por exemplo, que para iniciar a tarefa connectedAndroidTest, basta digitar o seguinte comando:

./gradlew cAT

As tarefas test e connectedAndroidTest executam testes em cada módulo e variante de build do projeto. Você pode executar testes apenas para um módulo específico do projeto, prefixando a tarefa test ou connectedAndroidTest com o nome do módulo e dois pontos (:). Por exemplo, o comando a seguir executa testes de unidade instrumentados apenas para o módulo mylibrary.

./gradlew mylibrary:connectedAndroidTest

Você também pode segmentar uma variante de build específica usando a sintaxe a seguir.

Para testes de unidade locais:
```
./gradlew testVariantNameUnitTest
```

Para testes de unidade de instrumentação:

./gradlew connectedVariantNameAndroidTest

Observação: se você não especificar um módulo de destino a ser testado, o Gradle analisará todos os módulos e executará testes para todas as variantes que correspondem ao nome de configuração especificado.

O Gradle também permite segmentar testes específicos usando a sinalização --tests. Por exemplo, o comando a seguir executa apenas os testes sampleTestMethod para a variante de build especificada. Para saber mais sobre como usar a sinalização --tests, leia a documentação do Gradle sobre filtrar testes (link em inglês).

./gradlew testVariantNameUnitTest --tests *.sampleTestMethod

Relatórios de vários módulos

Conforme descrito na Tabela 1, o Gradle salva os relatórios de teste 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, faça o seguinte:

No arquivo build.gradle do projeto, adicione as informações a seguir após todas as outras configurações no arquivo:
Groovy
```
apply plugin: 'android-reporting'
```
Kotlin
```
plugins {
    id("android-reporting")
}
```
Invoque a tarefa test ou connectedAndroidTest com 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 relatórios combinados no diretório PATH_TO_YOUR_PROJECT/build/.

Como executar testes com o adb

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

Para executar um teste a partir da linha de comando, execute adb shell para iniciar um shell de linha de comando no dispositivo ou emulador e execute o comando am instrument no shell. Você controla am e seus testes com sinalizações de linha de comando.

Como atalho, você pode iniciar um shell adb, chamar am instrument e especificar sinalizações de linha de comando em uma única linha de entrada. O shell é aberto no dispositivo ou no emulador, executa os testes, gera resultados e, por fim, retorna para a linha de comando no computador.

Para executar um teste com am instrument:

Se necessário, recompile o app principal e o pacote de teste.
Instale o pacote de teste e os principais arquivos do pacote do app 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 app em teste, e <runner_class> é o nome da classe de execução de teste Android usada. O nome do pacote do Android é o valor do atributo package do elemento manifest no arquivo de manifesto (AndroidManifest.xml) do pacote de teste. A classe de execução de teste do Android geralmente é AndroidJUnitRunner.

Os resultados do teste são exibidos em STDOUT.

Essa operação inicia um shell adb e executa um am instrument com os parâmetros especificados. Essa forma específica do comando executará todos os testes no pacote. Você pode controlar esse comportamento com sinalizações transmitidas para am instrument. Essas sinalizações são descritas na próxima seção.

Usar o comando "am instrument"

A sintaxe geral do comando am instrument é

am instrument [flags] <test_package>/<runner_class>

Os principais parâmetros de entrada para am instrument são descritos na tabela a seguir.

Parâmetro	Valor	Descrição
`<test_package>`	Nome do pacote Android de teste	Valor do atributo `package` do elemento `manifest` no arquivo de manifesto do pacote de teste.
`<runner_class>`	Nome da classe do executor de teste instrumentado em uso.	Geralmente é `AndroidJUnitRunner`.

As sinalizações para am instrument são descritas na tabela a seguir.

Sinalização	Valor	Descrição
`-w`	(nenhum)	Força `am instrument` a esperar até que a instrumentação termine antes de ser encerrado. O efeito esperado é manter o shell aberto até que os testes tenham terminado. Essa sinalização não é obrigatória, mas, quando não é utilizada, os resultados dos testes não são exibidos.
`-r`	(nenhum)	Exibe os resultados no formato bruto. Use essa sinalização quando quiser coletar medidas de desempenho, sem que elas sejam formatadas como resultados de teste. Essa sinalização foi desenvolvida para ser usada com `-e perf true` (documentado na seção Opções de instrumento).
`-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 por meio do 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 am instrument options. Só é possível usar esses pares de chave-valor com `AndroidJUnitRunner` ou com `InstrumentationTestRunner` e suas subclasses. 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 saber mais sobre as APIs ocultas e sobre 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 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 seguinte 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/android.support.test.runner.AndroidJUnitRunner

A tabela a seguir lista os pares chave-valor que podem ser usados 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 totalmente qualificado da classe Java para uma das classes de caso de teste. Somente essa classe de caso de teste é executada.
`class`	<class_name>#nome do método	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 `@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 será mantida no formato bruto e não será 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 aparecem 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 modificar o local do arquivo, use a chave `coverageFile`, descrita na entrada a seguir. Observação: essa opção requer um build do app 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`.

-e Notas de uso da sinalização

am instrument invoca onCreate(Bundle) com um Bundle contendo os pares chave-valor.
A chave package tem prioridade sobre a class. Se você especificar um pacote e, em seguida, especificar uma classe separadamente nesse pacote, o Android executará todos os testes no pacote e ignorará a chave class.
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 teste instrumentado:
- 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 UnitTests, digite:

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

am instrument gera o valor da sinalização -e, detecta a palavra-chave class e executa todos os métodos na classe UnitTests

Selecionar um subconjunto de testes

Para executar todos os testes em Foo1 e o método bar3 em Foo2, insira:

$ 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