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. Nesta página, explicamos como usar o Atest para executar testes do Android.

Para informações gerais sobre como programar testes para 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 seu ambiente 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 mais usados. Uma lista completa está disponível no atest --help.

Para mais informações sobre -b, -i e -t, consulte a seção Especificar etapas: build, instalação ou execução.

Especificar testes

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

• Nome do módulo
• Module:Class
• 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, assim:

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

Module:Class

Para executar uma única classe em um módulo, use Module:Class. Module é o mesmo que Module name. Class é o nome da classe de teste no arquivo .java e pode ser o nome 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 ao TradeFed (não modulares), insira o nome como aparece na saída do comando tradefed.sh list configs. Por exemplo:

Para executar o reboot.xml test:

atest example/reboot

Para executar o native-benchmark.xml test:

atest native-benchmark

Caminho do arquivo

O Atest permite executar testes baseados em módulos e em integração inserindo o caminho para o arquivo ou diretório de teste, conforme apropriado. Ele também permite executar uma única classe especificando o caminho para o arquivo Java dela. 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.

Execute no Android repo-root:

atest cts/tests/video

Execute 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 permite pesquisar testes por nome do pacote.

Exemplos:

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

Especificar etapas: build, instalação ou execução

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
• Instale o APK e execute os 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 o CTS, limpam o dispositivo depois da execução. Por isso, tentar executar o teste de novo 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 permite executar métodos específicos em uma classe de teste. Embora seja necessário criar todo o módulo, isso reduz o tempo necessário para executar os testes. Para executar métodos específicos, identifique a classe usando qualquer uma das maneiras compatíveis 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.

Como usar Module:Class:

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. Por isso, especificar um subconjunto de classes em um módulo melhora o desempenho em comparação com a execução do módulo inteiro.

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 GTest. Use -a para executar esses testes em todas as arquiteturas de dispositivo 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 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

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

atest

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

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 postsubmit 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 principais:

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

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

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

Executar testes em subdiretórios

Por padrão, o Atest só busca testes em arquivos TEST_MAPPING para cima (do diretório atual ou especificado 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 na iteração

Execute testes em iteração transmitindo o argumento --iterations. Seja aprovado ou reprovado, o Atest vai repetir o teste até atingir a iteração máxima.

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 o número máximo de iterações seja atingido.

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

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

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

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

Abordagem 2: execute apenas os testes com falha até serem aprovados ou até atingir o número máximo de iterações.

• Suponha que test-to-run tenha vários casos de teste e um dos testes falhe. Execute o teste com falha 10 vezes (por padrão) ou até que ele 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. Depois, 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

Transmitir 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 aos módulos.