Executar testes (Atest)

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 como escrever testes para o Android, consulte Testes da plataforma Android.

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

Para informações sobre como executar testes em arquivos TEST_MAPPING usando o Atest, consulte 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 do Atest têm o seguinte formato:

atest test-to-run [optional-arguments]

Argumentos opcionais

A tabela a seguir lista os argumentos usados com frequência. 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 este:

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 como ele 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 Módulo:classe. Módulo é o mesmo descrito em Nome do módulo. Classe é o nome da classe de teste no arquivo .java e pode ser o nome totalmente qualificado da classe 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 ao TradeFed (não modulares), insira o nome como ele aparece na saída do comando tradefed.sh list configs. Por exemplo:

Para executar o reboot.xml teste:

atest example/reboot

Para executar o native-benchmark.xml teste:

atest native-benchmark

Caminho do arquivo

O Atest oferece suporte à execução de testes baseados em módulos e testes baseados em integração, inserindo 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. 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 repo-root do Android:

atest cts/tests/video

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

    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 repo-root do Android:

    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 repo-root do Android:

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

Nome do pacote

O Atest oferece suporte à pesquisa de testes por 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 executar. Se você não especificar uma opção, todas as etapas serão executadas.

• Criar apenas destinos: 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 ignorar a etapa de limpeza ou desmontagem. Muitos testes, como o CTS, limpam o dispositivo após a execução do teste. Portanto, tentar executar o teste novamente com -t vai falhar sem o parâmetro --disable-teardown. Use -d antes de -t para ignorar 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 maneiras aceitas 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 maneiras preferenciais de executar um único método, testFlagChange. Esses exemplos são preferíveis a 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 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 classes e módulos diferentes:

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 GTest

O Atest pode executar binários 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 GTest específico a ser executado, use dois pontos (:) para especificar o nome do teste e um símbolo de 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 o teste inteiro:

atest inputflinger_tests:InputDispatcherTest

Ou execute um teste individual usando o seguinte:

atest inputflinger_tests:InputDispatcherTest#InjectInputEvent_ValidatesKeyEvents

Executar testes no 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 atual e pai:

atest

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

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

Executar um grupo de testes especificado

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

Execute testes de pós-envio em arquivos TEST_MAPPING nos diretórios atual e pai:

atest :postsubmit

Execute testes de todos os grupos em arquivos TEST_MAPPING:

atest :all

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

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

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

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 fornecido para os diretórios pai). 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 em iteração

Execute testes em iteração transmitindo o argumento --iterations. Seja aprovado ou reprovado, o Atest vai 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 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 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 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 for aprovado ou atingir a 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 artefatos de build e, em seguida, use os exemplos a seguir 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 módulos de teste. Para adicionar opções de linha de comando do TradeFed à execução de teste, use a estrutura a seguir 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 opções de módulo de teste para 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

Transmita opções para um tipo ou classe de executor:

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 opções somente de teste, consulte Transmitir opções para os módulos.