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.

Opção	Opção longa	Descrição
-b	--build	Cria destinos de teste. (padrão)
-i	--install	Instala artefatos de teste (APKs) no dispositivo. (padrão)
-t	--test	Executa os testes. (padrão)
-s	--serial	Executa os testes no dispositivo especificado. Só é possível testar um dispositivo por vez.
-d	--disable-teardown	Desativa a desmontagem e a limpeza do teste.
	--dry-run	Simula testes sem criar, instalar ou executar testes.
-m	--rebuild-module-info	Força uma reconstrução do arquivo module-info.json.
-w	--wait-for-debugger	Aguarda a conclusão do depurador antes da execução.
-v	--verbose	Mostra o registro no nível DEBUG.
	--iterations	Loop-run executa testes até que a iteração máxima seja alcançada. (10 por padrão)
	--rerun-until-failure [COUNT=10]	Repete todos os testes até que ocorra uma falha ou a iteração máxima seja alcançada. (10 por padrão)
	--retry-any-failure [COUNT=10]	Repete os testes com falha até que sejam aprovados ou até que a iteração máxima seja alcançada. (10 por padrão)
	--start-avd	Cria automaticamente um AVD e executa testes no dispositivo virtual.
	--acloud-create	Cria um AVD usando o comando acloud.
	--[CUSTOM_ARGS]	Especifica argumentos personalizados para os executores de teste.
-a	--all-abi	Executa os testes para todas as arquiteturas de dispositivo disponíveis.
	--host	Executa o teste completamente no host sem um dispositivo. Observação: a execução de um teste de host que exige um dispositivo com --host vai falhar.
	--history	Mostra os resultados do teste em ordem cronológica.
	--latest-result	Imprime o resultado do teste mais recente.

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

Observação: para executar testes que não são de módulo integrados ao TradeFed (TF), use Teste de integração do TF como um identificador.

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

Observação: para reduzir o tempo que o Atest leva para localizar o teste correto, recomendamos usar o caminho completo da classe, conforme mostrado no último exemplo.

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

Observação: para reduzir o tempo que o Atest leva para localizar o teste correto, recomendamos usar Module:Class em vez de apenas o nome da classe sempre que possível.

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.

Execução 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.

Observação: -b e -t podem ser executados individualmente, mas -i não pode ser executado sem -t.

• 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

Observação: como -t desativa a configuração/instalação e a remoção/limpeza do dispositivo, é possível executar o teste com atest -t test-to-run quantas vezes quiser.

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 ao uso exclusivo do nome da classe, porque especificar o módulo ou a localização 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 turmas

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

Observação: se você só precisa executar testes para uma arquitetura de dispositivo específica, use atest -- --abi arm64-v8a ou atest -- --abi armeabi-v7a.

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 de pré-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.

• Para 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.

Observação: --acloud-create precisa ser o ÚLTIMO argumento opcional. Todos os argumentos que seguem são tratados como argumentos posicionais para o AVD.

Observação: --acloud-create e --start-avd não excluem AVDs recém-criados. Os usuários precisam excluir esses arquivos manualmente.

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.