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 :
|
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
|
Teste de unidade instrumentado |
Execute a tarefa 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
|
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 blocobuildscript{}
:Groovy
apply plugin 'android-reporting'
Kotlin
apply(plugin = "android-reporting")
Invoque a tarefa
test
ouconnectedAndroidTest
usando a tarefamergeAndroidReports
. 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_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 |
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
invocaonCreate(Bundle)
com umBundle
contendo os pares de chave-valor.- A chave
package
tem prioridade sobre aclass
. 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
eunit
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 testebar1
, eFoo2
, que contém os métodos de testebar2
ebar3
- 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
.