Executar testes (Atest)

O Atest é uma ferramenta de linha de comando que permite que os usuários criem, instalem e executem testes do Android localmente, acelerando muito as execuções repetidas de testes, sem exigir conhecimento das opções de linha de comando do arcabouço de testes da Trade Federation. Esta página explica como usar o Atest para executar testes do Android.

Para informações gerais sobre a criação de testes para Android, consulte Testes de plataforma Android.

Para informações sobre a estrutura geral do Atest, consulte o Guia para desenvolvedores do Atest.

Para informações sobre como executar testes em arquivos TEST_MAPPING pelo Atest, consulte Como executar testes em arquivos TEST_MAPPING.

Para adicionar um recurso ao Atest, siga o Fluxo de trabalho do desenvolvedor do Atest.

Configurar o ambiente

Para configurar o ambiente do Atest, siga as instruções em Configurar o ambiente, Escolher um destino e Criar o código.

Uso básico

Os comandos Atest têm o seguinte formato:

 atest test-to-run [optional-arguments] 

Argumentos opcionais

A tabela a seguir lista os argumentos mais usados. Uma lista completa está disponível em atest --help.

Para mais informações sobre -b, -i e -t, consulte a seção Especificar etapas: criar, instalar ou executar.

Especificar testes

Para executar testes, especifique um ou mais testes usando um dos seguintes identificadores:

• Nome do módulo
• Módulo:classe
• Nome da classe
• Teste de integração do Tradefed
• Caminho do arquivo
• Nome do pacote

Separe as referências a vários testes com espaços, como esta:

 atest test-identifier-1 test-identifier-2 

Nome do módulo

Para executar um módulo de teste inteiro, use o nome dele. Insira o nome conforme aparece nas variáveis LOCAL_MODULE ou LOCAL_PACKAGE_NAME no arquivo Android.mk ou Android.bp do teste.

Exemplos:

 atest FrameworksServicesTests atest CtsVideoTestCases 

Módulo:classe

Para executar uma única classe em um módulo, use Module:Class. Module é o mesmo descrito em Module name. Class é o nome da classe de teste no arquivo .java e pode ser o nome de classe totalmente qualificado ou o nome básico.

Exemplos:

 atest CtsVideoTestCases:VideoEncoderDecoderTest atest FrameworksServicesTests:ScreenDecorWindowTests atest FrameworksServicesTests:com.android.server.wm.ScreenDecorWindowTests 

Nome da classe

Para executar uma única classe sem declarar explicitamente um nome de módulo, use o nome da classe.

Exemplos:

 atest ScreenDecorWindowTests atest VideoEncoderDecoderTest 

Teste de integração do Tradefed

Para executar testes integrados diretamente no TradeFed (não módulos), insira o nome conforme aparece na saída do comando tradefed.sh list configs. Por exemplo:

Para executar o teste reboot.xml:

 atest example/reboot 

Para executar o teste native-benchmark.xml:

 atest native-benchmark 

Caminho do arquivo

O Atest oferece suporte à execução de testes baseados em módulo e em integração digitando o caminho para o arquivo ou diretório de teste, conforme apropriado. Ele também oferece suporte à execução de uma única classe especificando o caminho para o arquivo Java da classe. Os caminhos relativos e absolutos são aceitos.

Executar um módulo

Os exemplos a seguir mostram duas maneiras de executar o módulo CtsVideoTestCases usando um caminho de arquivo.

Executar no Android repo-root:

 atest cts/tests/video 

Executar no Android repo-root/cts/tests/video:

     atest . 

Executar uma classe de teste

O exemplo a seguir mostra como executar uma classe específica no módulo CtsVideoTestCases usando um caminho de arquivo.

No Android repo-root:

     atest cts/tests/video/src/android/video/cts/VideoEncoderDecoderTest.java 

Executar um teste de integração

O exemplo a seguir mostra como executar um teste de integração usando um caminho de arquivo do Android repo-root:

     atest tools/tradefederation/contrib/res/config/example/reboot.xml 

Nome do pacote

O Atest oferece suporte à pesquisa de testes pelo nome do pacote.

Exemplos:

     atest com.android.server.wm     atest com.android.uibench.janktests 

Especificar etapas: criar, instalar ou executar

Use as opções -b, -i e -t para especificar quais etapas serão executadas. Se você não especificar uma opção, todas as etapas serão executadas.

• Destinos de build somente: atest -b test-to-run
• Executar apenas testes: atest -t test-to-run
• Instalar o APK e executar testes: atest -it test-to-run
• Criar e executar, mas não instalar: atest -bt test-to-run

O Atest pode forçar um teste a pular a etapa de limpeza ou desmontagem. Muitos testes, como CTS, limpam o dispositivo depois que o teste é executado. Portanto, tentar executar o teste com -t vai falhar sem o parâmetro --disable-teardown. Use -d antes de -t para pular a etapa de limpeza do teste e testar de forma iterativa.

 atest -d test-to-run atest -t test-to-run 

Executar métodos específicos

O Atest oferece suporte à execução de métodos específicos em uma classe de teste. Embora todo o módulo precise ser criado, isso reduz o tempo necessário para executar os testes. Para executar métodos específicos, identifique a classe usando qualquer uma das formas com suporte para identificar uma classe (Module:Class, caminho do arquivo etc.) e anexe o nome do método:

 atest reference-to-class#method1 

Ao especificar vários métodos, separe-os com vírgulas:

 atest reference-to-class#method1,method2,method3 

Exemplos:

 atest com.android.server.wm.ScreenDecorWindowTests#testMultipleDecors atest FrameworksServicesTests:ScreenDecorWindowTests#testFlagChange,testRemoval 

Os dois exemplos a seguir mostram as maneiras preferidas de executar um único método, testFlagChange. Esses exemplos são preferidos em vez de usar apenas o nome da classe porque especificar o módulo ou o local do arquivo Java permite que o Atest encontre o teste muito mais rapidamente.

Usando o módulo:Classe:

 atest FrameworksServicesTests:ScreenDecorWindowTests#testFlagChange 

No Android repo-root:

 atest frameworks/base/services/tests/wmtests/src/com/android/server/wm/ScreenDecorWindowTests.java#testFlagChange 

Vários métodos podem ser executados em diferentes classes e módulos:

 atest FrameworksServicesTests:ScreenDecorWindowTests#testFlagChange,testRemoval ScreenDecorWindowTests#testMultipleDecors 

Executar várias classes

Para executar várias classes, separe-as com espaços da mesma forma que para executar vários testes. O Atest cria e executa classes de maneira eficiente. Portanto, especificar um subconjunto de classes em um módulo melhora o desempenho em relação à execução de todo o módulo.

Para executar duas classes no mesmo módulo:

 atest FrameworksServicesTests:ScreenDecorWindowTests FrameworksServicesTests:DimmerTests 

Para executar duas classes em módulos diferentes:

 atest FrameworksServicesTests:ScreenDecorWindowTests CtsVideoTestCases:VideoEncoderDecoderTest 

Executar binários do GTest

O Atest pode executar binários do GTest. Use -a para executar esses testes em todas as arquiteturas de dispositivos disponíveis, que neste exemplo são armeabi-v7a (ARM de 32 bits) e arm64-v8a (ARM de 64 bits).

Exemplo de teste de entrada:

 atest -a libinput_tests inputflinger_tests 

Para selecionar um binário específico do GTest a ser executado, use dois-pontos (:) para especificar o nome do teste e uma hashtag (#) para especificar um método individual.

Por exemplo, para a seguinte definição de teste:

 TEST_F(InputDispatcherTest, InjectInputEvent_ValidatesKeyEvents) 

Execute o seguinte para especificar todo o teste:

 atest inputflinger_tests:InputDispatcherTest 

Ou execute um teste individual usando o seguinte:

 atest inputflinger_tests:InputDispatcherTest#InjectInputEvent_ValidatesKeyEvents 

Executar testes em TEST_MAPPING

O Atest pode executar testes em arquivos TEST_MAPPING.

Executar testes de pré-envio implicitamente

Execute testes antes do envio em arquivos TEST_MAPPING nos diretórios atuais e principais:

 atest 

Execute testes antes do envio em arquivos TEST_MAPPING em /path/to/project e nos diretórios pais:

 atest --test-mapping /path/to/project 

Executar um grupo de teste especificado

Os grupos de teste disponíveis são: presubmit(padrão), postsubmit, mainline-presubmit e all.

Execute testes pós-envio em arquivos TEST_MAPPING nos diretórios atuais e principais:

 atest :postsubmit 

Execute testes de todos os grupos nos arquivos TEST_MAPPING:

 atest :all 

Execute testes pós-envio em arquivos TEST_MAPPING em /path/to/project e nos diretórios pais:

 atest --test-mapping /path/to/project:postsubmit 

Execute testes principais em arquivos TEST_MAPPING em /path/to/project e nos diretórios pais:

 atest --test-mapping /path/to/project:mainline-presubmit 

Executar testes em subdiretórios

Por padrão, o Atest só pesquisa testes em arquivos TEST_MAPPING para cima (do diretório atual ou especificado para os diretórios pais). Se você também quiser executar testes em arquivos TEST_MAPPING nos subdiretórios, use --include-subdirs para forçar o Atest a incluir esses testes também:

atest --include-subdirs /path/to/project

Executar testes na iteração

Execute testes na iteração transmitindo o argumento --iterations. Seja bem-sucedido ou não, o Atest vai repetir o teste até que a iteração máxima seja alcançada.

Exemplos:

Por padrão, o Atest itera 10 vezes. O número de iterações precisa ser um número inteiro positivo.

 atest test-to-run --iterations atest test-to-run --iterations 5 

As abordagens a seguir facilitam a detecção de testes instáveis:

Abordagem 1: execute todos os testes até que ocorra uma falha ou a iteração máxima seja alcançada.

• Pare quando ocorrer uma falha ou a iteração chegar à 10ª rodada (por padrão).

   atest test-to-run --rerun-until-failure 

• Pare quando ocorrer uma falha ou a iteração chegar à 100ª rodada.

   atest test-to-run --rerun-until-failure 100 

Abordagem 2: execute apenas testes com falha até que sejam aprovados ou até que a iteração máxima seja alcançada.

• Suponha que test-to-run tenha vários casos de teste e um deles falhe. Execute apenas o teste com falha 10 vezes (por padrão) ou até que o teste seja aprovado.

   atest test-to-run --retry-any-failure 

• Pare de executar o teste com falha quando ele passar ou chegar à 100ª rodada.

   atest test-to-run --retry-any-failure 100 

Executar testes em AVDs

O Atest pode executar testes em um AVD recém-criado. Execute acloud create para criar um AVD e criar artefatos. Em seguida, use os exemplos abaixo para executar os testes.

Inicie um AVD e execute testes nele:

 acloud create --local-instance --local-image && atest test-to-run 

Inicie um AVD como parte de uma execução de teste:

 atest test-to-run --acloud-create "--local-instance --local-image" 

Para mais informações, execute acloud create --help.

Transmitir opções para o módulo

O Atest pode transmitir opções para testar módulos. Para adicionar opções de linha de comando do TradeFed à execução de teste, use a estrutura abaixo e verifique se os argumentos personalizados seguem o formato de opção de linha de comando do Tradefed.

 atest test-to-run -- [CUSTOM_ARGS] 

Transmita as opções do módulo de teste para os preparadores ou executores de teste de destino definidos no arquivo de configuração de teste:

 atest test-to-run -- --module-arg module-name:option-name:option-value atest GtsPermissionTestCases -- --module-arg GtsPermissionTestCases:ignore-business-logic-failure:true 

Transmita opções para um tipo ou classe de execução:

 atest test-to-run -- --test-arg test-class:option-name:option-value atest CtsVideoTestCases -- --test-arg com.android.tradefed.testtype.JarHosttest:collect-tests-only:true 

Para mais informações sobre as opções somente para teste, consulte Transmitir opções para os módulos.