A Visualização do desenvolvedor para Android 11 já está disponível. Teste e compartilhe seu feedback.

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 Android no seu ambiente de programação.

Executar testes

É possível executar testes a partir da 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 a partir do projeto do Gradle por meio da linha de comando. Para saber mais sobre como compilar testes de unidade para o app, consulte Compilar testes de unidade eficazes.

Executar testes de unidade com o Gradle

O plug-in do Android para o Gradle permite executar testes de unidade a partir do projeto do Gradle por meio da linha de comando. Para saber mais sobre como compilar testes de unidade para o app, consulte Compilar testes de unidade eficazes.

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 resultados 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 resultados 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 abreviaturas 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 de instrumentados apenas para o módulo mylibrary.

    ./gradlew mylibrary:connectedAndroidTest
    

Você também pode segmentar uma variação 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 variações correspondentes 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 filtragem de teste (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:

  1. No seu arquivo build.gradle do projeto, adicione o seguinte após todas as outras configurações no arquivo:
        apply plugin: 'android-reporting'
        
  2. 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
        

Quando o Gradle conclui a execução de todos os testes, ele salva os relatórios combinados no diretório PATH_TO_YOUR_PROJECT/build/.

Executar testes com o adb

Quando você executa testes a partir da 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 seus testes, produz saídas e, por fim, retorna para a linha de comando no computador.

Para executar um teste com am instrument:

  1. Se necessário, recompile o app principal e o pacote de teste.
  2. Instale o pacote de teste e os principais arquivos do pacote do app 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 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. Esse sinalizador não é obrigatório, mas, quando não é utilizado, 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 Opções de am instrument. Só é possível usar esses pares de chave-valor com AndroidJUnitRunner ou com InstrumentationTestRunner e suas subclasses. O uso desses 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 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 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, esta invocação de AndroidJUnitRunner fornece vários 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_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 uma build do app em teste instrumentado por EMMA, que você pode gerar 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, 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