Executar testes (Atest)

Atest é uma ferramenta de linha de comando que permite aos usuários criar, instalar e executar testes do Android localmente, acelerando bastante a repetição de testes sem exigir conhecimento das opções de linha de comando do equipamento de teste da Federação de Comércio . Esta página explica como usar o Atest para executar testes do Android.

Para obter informações gerais sobre como escrever testes para Android, consulte Testes da plataforma Android .

Para obter informações sobre a estrutura geral do Atest, consulte o Atest Developer Guide .

Para obter informações sobre como executar testes em arquivos TEST_MAPPING por meio do Atest, consulte Executando testes em arquivos TEST_MAPPING .

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

Configure seu ambiente

Para configurar seu ambiente Atest, siga as instruções em Configurando o ambiente , Escolhendo um destino e Construindo o código .

Uso básico

Os comandos Atest assumem o seguinte formato:

atest test-to-run [optional-arguments]

Argumentos opcionais

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

Opção	Opção longa	Descrição
-b	--build	Constrói alvos 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. Um dispositivo pode ser testado por vez.
-d	--disable-teardown	Desativa a desmontagem e limpeza do teste.
	--dry-run	Executa o Atest sem realmente construir, 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 de executar.
-v	--verbose	Exibe o log de nível DEBUG.
	--iterations	Executa testes em loop até que a iteração máxima seja atingida. (10 por padrão)
	--rerun-until-failure [COUNT=10]	Executa novamente todos os testes até que ocorra uma falha ou a iteração máxima seja atingida. (10 por padrão)
	--retry-any-failure [COUNT=10]	Executa novamente os testes que falharam até serem aprovados ou a iteração máxima ser atingida. (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 customizados para os executores de teste.
-a	--all-abi	Executa os testes para todas as arquiteturas de dispositivos disponíveis.
	--host	Executa o teste completamente no host sem dispositivo. Nota: A execução de um teste de host que requer um dispositivo com --host falhará.
	--history	Mostra os resultados dos testes em ordem cronológica.
	--latest-result	Imprime o resultado do teste mais recente.

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

Especifique testes

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

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

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

atest test-identifier-1 test-identifier-2

Nome do módulo

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

Exemplos:

atest FrameworksServicesTests
atest CtsVideoTestCases

Nota: Para executar testes sem módulo integrados ao TradeFed (TF), use o TF Integration Test como identificador.

Módulo:Aula

Para executar uma única classe dentro de um módulo, use Module:Class . O módulo é igual ao descrito em Nome do módulo . Classe é o nome da classe de teste no arquivo .java e pode ser o nome completo da classe ou o nome básico.

Exemplos:

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

Nota: Para reduzir o tempo que o Atest leva para localizar o teste correto, recomendamos usar o caminho de classe completo conforme mostrado no último exemplo.

Nome da classe

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

Exemplos:

atest ScreenDecorWindowTests
atest VideoEncoderDecoderTest

Nota: 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 Tradefed

Para executar testes integrados diretamente ao 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 de arquivo

Atest oferece suporte à execução de testes baseados em módulo e testes baseados em integração, inserindo o caminho para seu arquivo ou diretório de teste, conforme apropriado. Ele também suporta a execução de uma única classe especificando o caminho para o arquivo Java da classe. São suportados caminhos relativos e absolutos.

Execute um módulo

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

Execute a partir do repo-root Android:

atest cts/tests/video

Execute a partir do Android repo-root/cts/tests/video :

    atest .

Execute uma classe de teste

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

Do repo-root Android:

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

Execute 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

Atest oferece suporte à pesquisa de testes por nome de pacote.

Exemplos:

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

Especifique as etapas: construir, instalar ou executar

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

Nota: -b e -t podem ser executados individualmente, mas -i não podem ser executados sem -t .

• Apenas alvos de compilação: atest -b test-to-run
• Execute apenas testes: atest -t test-to-run
• Instale o apk e execute os testes: atest -it test-to-run
• Crie e execute, mas não instale: atest -bt test-to-run

Atest pode forçar um teste a pular a etapa de limpeza ou desmontagem. Muitos testes, como o CTS, limpam o dispositivo após a execução do teste, portanto, tentar executar novamente o teste com -t falhará sem o parâmetro --disable-teardown . Use -d antes de -t para pular a etapa de limpeza do teste e testar iterativamente.

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

Observação: como -t desativa a configuração/instalação e a desmontagem/limpeza do dispositivo, você pode executar novamente o teste com atest -t test-to-run quantas vezes desejar.

Execute métodos específicos

Atest oferece suporte à execução de métodos específicos em uma classe de teste. Embora todo o módulo precise ser construído, isso reduz o tempo necessário para executar os testes. Para executar métodos específicos, identifique a classe usando qualquer uma das formas suportadas para identificar uma classe (Módulo:Classe, 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 formas preferidas de executar um único método, testFlagChange . Esses exemplos são preferíveis ao uso apenas 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 Módulo:Classe:

atest FrameworksServicesTests:ScreenDecorWindowTests#testFlagChange

Do repo-root Android:

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

Vários métodos podem ser executados a partir de diferentes classes e módulos:

atest FrameworksServicesTests:ScreenDecorWindowTests#testFlagChange,testRemoval ScreenDecorWindowTests#testMultipleDecors

Execute várias aulas

Para executar várias classes, separe-as com espaços da mesma forma que para executar vários testes. Atest cria e executa classes com eficiência, 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 aulas em módulos diferentes:

atest FrameworksServicesTests:ScreenDecorWindowTests CtsVideoTestCases:VideoEncoderDecoderTest

Execute binários GTest

Atest pode executar binários GTest. Use -a para executar esses testes para 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ê precisar apenas executar testes para uma arquitetura de dispositivo específica, use atest -- --abi arm64-v8a ou atest -- --abi armeabi-v7a

Para selecionar um binário GTest específico para execução, use dois pontos (:) para especificar o nome do teste e uma hashtag (#) para especificar ainda mais 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

Execute testes em TEST_MAPPING

Atest pode executar testes em arquivos TEST_MAPPING .

Execute testes de pré-envio implicitamente

Execute testes de pré-envio em arquivos TEST_MAPPING nos diretórios atuais e pai:

atest

Execute testes de pré-envio em arquivos TEST_MAPPING em /path/to/project e seus diretórios pai:

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

Execute 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 pai:

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 seus diretórios pai:

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

Execute testes de linha principal em arquivos TEST_MAPPING em /path/to/project e seus diretórios pai:

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

Execute testes em subdiretórios

Por padrão, o Atest pesquisa apenas testes em arquivos TEST_MAPPING para cima (do diretório atual ou fornecido para seus diretórios pai). Se você também deseja 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

Execute testes em iteração

Execute testes em iteração passando o argumento --iterations . Quer seja aprovado ou reprovado, o Atest repetirá o teste até que a iteração máxima seja atingida.

Exemplos:

Por padrão, o Atest itera 10 vezes. O número de iterações deve 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 atingida.

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

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

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

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

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

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

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

• Pare de executar o teste que falhou quando ele passar ou atingir a 100ª rodada.

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

Execute testes em AVDs

Atest é capaz de executar testes em um AVD recém-criado. Execute acloud create para criar um AVD e construir artefatos e, em seguida, use os exemplos a seguir para executar seus 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 obter mais informações, execute acloud create --help .

Nota: --acloud-create deve ser o ÚLTIMO argumento opcional. Quaisquer argumentos que o sigam são tratados como argumentos posicionais para o AVD.

Nota: --acloud-create e --start-avd não excluem AVDs recém-criados. Os usuários devem excluí-los manualmente.

Passar opções para o módulo

Atest é capaz de passar opções para módulos de teste. Para adicionar opções de linha de comando TradeFed à sua execução de teste, use a estrutura a seguir e certifique-se de que seus argumentos personalizados sigam o formato de opção de linha de comando Tradefed.

atest test-to-run -- [CUSTOM_ARGS]

Passe as opções do módulo de teste para os preparadores de destino ou executores de teste 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

Passe opções para um tipo ou classe de runner:

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 obter mais informações sobre opções somente de teste, consulte Passar opções para os módulos .