Ejecutar pruebas (Atest)

Atest es una herramienta de línea de comandos que permite a los usuarios compilar, instalar y ejecutar pruebas de Android de forma local, lo que agiliza significativamente las ejecuciones repetidas de pruebas sin requerir conocimiento sobre las opciones de la línea de comandos del agente de prueba de Trade Federation. En esta página, se explica cómo usar Atest para ejecutar pruebas de Android.

Para obtener información general sobre cómo escribir pruebas para Android, consulta Pruebas de la plataforma de Android.

Para obtener información sobre la estructura general de Atest, consulta la Guía para desarrolladores de Atest.

Para obtener información sobre cómo ejecutar pruebas en archivos TEST_MAPPING a través de Atest, consulta Cómo ejecutar pruebas en archivos TEST_MAPPING.

Para agregar una función a Atest, sigue el Flujo de trabajo del desarrollador de Atest.

Desarrolla tu entorno

Para configurar tu entorno de atest, sigue las instrucciones en Cómo configurar el entorno, Cómo elegir un destino y Cómo compilar el código.

Uso básico

Los comandos de atest tienen el siguiente formato:

atest test-to-run [optional-arguments]

Argumentos opcionales

En la siguiente tabla, se enumeran los argumentos que se usan con mayor frecuencia. Puedes consultar la lista completa en atest --help.

Opción Opción larga Descripción
-b --build Compila destinos de prueba. (predeterminado)
-i --install Instala artefactos de prueba (APKs) en el dispositivo. (predeterminado)
-t --test Ejecuta las pruebas. (predeterminado)
-s --serial Ejecuta las pruebas en el dispositivo especificado. Solo se puede probar un dispositivo a la vez.
-d --disable-teardown Inhabilita la limpieza y el desmantelamiento de la prueba.
--dry-run Ejecuta Atest en modo de prueba sin compilar, instalar ni ejecutar pruebas.
-m --rebuild-module-info Fuerza una recompilación del archivo module-info.json.
-w --wait-for-debugger Espera a que finalice el depurador antes de ejecutar.
-v --verbose Muestra el registro de nivel DEBUG.
--iterations Ejecuta pruebas en bucle hasta que se alcanza la iteración máxima. (10 de forma predeterminada)
--rerun-until-failure [COUNT=10] Vuelve a ejecutar todas las pruebas hasta que se produzca una falla o se alcance la cantidad máxima de iteraciones. (10 de forma predeterminada)
--retry-any-failure [COUNT=10] Vuelve a ejecutar las pruebas con errores hasta que se aprueben o se alcance la iteración máxima. (10 de forma predeterminada)
--start-avd Crea automáticamente un AVD y ejecuta pruebas en el dispositivo virtual.
--acloud-create Crea un AVD con el comando acloud.
--[CUSTOM_ARGS] Especifica argumentos personalizados para los ejecutores de pruebas.
-a --all-abi Ejecuta las pruebas para todas las arquitecturas de dispositivos disponibles.
--host Ejecuta la prueba por completo en el host sin un dispositivo.
Nota: Fallará la ejecución de una prueba de host que requiera un dispositivo con --host.
--history Muestra los resultados de las pruebas en orden cronológico.
--latest-result Imprime el resultado de la prueba más reciente.

Para obtener más información sobre -b, -i y -t, consulta la sección Cómo especificar pasos: compilar, instalar o ejecutar.

Especifica pruebas

Para ejecutar pruebas, especifica una o más pruebas con uno de los siguientes identificadores:

  • Nombre del módulo
  • Module:Class
  • Nombre de clase
  • Prueba de integración de Tradefed
  • Ruta de acceso al archivo
  • Nombre de paquete

Separa las referencias a varias pruebas con espacios, de la siguiente manera:

atest test-identifier-1 test-identifier-2

Nombre del módulo

Para ejecutar un módulo de prueba completo, usa su nombre. Ingresa el nombre tal como aparece en las variables LOCAL_MODULE o LOCAL_PACKAGE_NAME en el archivo Android.mk o Android.bp de esa prueba.

Ejemplos:

atest FrameworksServicesTests
atest CtsVideoTestCases

Module:Class

Para ejecutar una sola clase dentro de un módulo, usa Module:Class. Módulo es lo mismo que se describe en Nombre del módulo. Class es el nombre de la clase de prueba en el archivo .java y puede ser el nombre de clase completamente calificado o el nombre básico.

Ejemplos:

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

Nombre de clase

Para ejecutar una sola clase sin indicar de forma explícita un nombre de módulo, usa el nombre de la clase.

Ejemplos:

atest ScreenDecorWindowTests
atest VideoEncoderDecoderTest

Prueba de integración de Tradefed

Para ejecutar pruebas que se integran directamente en Tradefed (no son módulos), ingresa el nombre tal como aparece en el resultado del comando tradefed.sh list configs. Por ejemplo:

Para ejecutar la prueba de reboot.xml, haz lo siguiente:

atest example/reboot

Para ejecutar la prueba de native-benchmark.xml, haz lo siguiente:

atest native-benchmark

Ruta de acceso al archivo

Atest admite la ejecución de pruebas basadas en módulos y pruebas basadas en la integración ingresando la ruta de acceso a su archivo o directorio de prueba según corresponda. También admite la ejecución de una sola clase especificando la ruta de acceso al archivo Java de la clase. Se admiten rutas de acceso relativas y absolutas.

Ejecuta un módulo

En los siguientes ejemplos, se muestran dos formas de ejecutar el módulo CtsVideoTestCases con una ruta de acceso al archivo.

Ejecuta desde repo-root de Android:

atest cts/tests/video

Ejecuta desde repo-root/cts/tests/video de Android:

    atest .

Cómo ejecutar una clase de prueba

En el siguiente ejemplo, se muestra cómo ejecutar una clase específica dentro del módulo CtsVideoTestCases con una ruta de acceso al archivo.

Desde Android repo-root:

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

Ejecuta una prueba de integración

En el siguiente ejemplo, se muestra cómo ejecutar una prueba de integración con una ruta de acceso a un archivo desde repo-root de Android:

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

Nombre de paquete

Atest admite la búsqueda de pruebas por nombre de paquete.

Ejemplos:

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

Especifica los pasos: Compilar, instalar o ejecutar

Usa las opciones -b, -i y -t para especificar qué pasos ejecutar. Si no especificas una opción, se ejecutarán todos los pasos.

  • Solo objetivos de compilación: atest -b test-to-run
  • Ejecutar solo pruebas: atest -t test-to-run
  • Instala el APK y ejecuta pruebas: atest -it test-to-run
  • Compila y ejecuta, pero no instales: atest -bt test-to-run

Atest puede forzar una prueba para que omita el paso de limpieza o desmontaje. Muchas pruebas, como las del CTS, limpian el dispositivo después de que se ejecuta la prueba, por lo que intentar volver a ejecutar la prueba con -t fallará sin el parámetro --disable-teardown. Usa -d antes de -t para omitir el paso de limpieza de la prueba y realizar pruebas de forma iterativa.

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

Cómo ejecutar métodos específicos

Atest admite la ejecución de métodos específicos dentro de una clase de prueba. Aunque se debe compilar todo el módulo, esto reduce el tiempo necesario para ejecutar las pruebas. Para ejecutar métodos específicos, identifica la clase con cualquiera de las formas admitidas para identificar una clase (Module:Class, ruta de acceso al archivo, etcétera) y agrega el nombre del método:

atest reference-to-class#method1

Cuando especifiques varios métodos, sepáralos con comas:

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

Ejemplos:

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

En los siguientes dos ejemplos, se muestran las formas preferidas de ejecutar un solo método, testFlagChange. Estos ejemplos son preferibles a usar solo el nombre de la clase, ya que especificar la ubicación del módulo o del archivo Java permite que Atest encuentre la prueba mucho más rápido.

Usa Module:Class:

atest FrameworksServicesTests:ScreenDecorWindowTests#testFlagChange

Desde Android repo-root:

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

Se pueden ejecutar varios métodos desde diferentes clases y módulos:

atest FrameworksServicesTests:ScreenDecorWindowTests#testFlagChange,testRemoval ScreenDecorWindowTests#testMultipleDecors

Ejecuta varias clases

Para ejecutar varias clases, sepáralas con espacios de la misma manera que para ejecutar varias pruebas. Atest compila y ejecuta clases de manera eficiente, por lo que especificar un subconjunto de clases en un módulo mejora el rendimiento en comparación con la ejecución de todo el módulo.

Para ejecutar dos clases en el mismo módulo, haz lo siguiente:

atest FrameworksServicesTests:ScreenDecorWindowTests FrameworksServicesTests:DimmerTests

Para ejecutar dos clases en módulos diferentes, haz lo siguiente:

atest FrameworksServicesTests:ScreenDecorWindowTests CtsVideoTestCases:VideoEncoderDecoderTest

Ejecuta objetos binarios de GTest

Atest puede ejecutar objetos binarios de GTest. Usa -a para ejecutar estas pruebas en todas las arquitecturas de dispositivos disponibles, que, en este ejemplo, son armeabi-v7a (ARM de 32 bits) y arm64-v8a (ARM de 64 bits).

Ejemplo de prueba de entrada:

atest -a libinput_tests inputflinger_tests

Para seleccionar un archivo binario de GTest específico para ejecutar, usa dos puntos (:) para especificar el nombre de la prueba y un signo de número (#) para especificar aún más un método individual.

Por ejemplo, para la siguiente definición de prueba: 

TEST_F(InputDispatcherTest, InjectInputEvent_ValidatesKeyEvents)

Ejecuta el siguiente comando para especificar la prueba completa: 

atest inputflinger_tests:InputDispatcherTest

También puedes ejecutar una prueba individual con el siguiente comando: 

atest inputflinger_tests:InputDispatcherTest#InjectInputEvent_ValidatesKeyEvents

Ejecuta pruebas en TEST_MAPPING

Atest puede ejecutar pruebas en archivos TEST_MAPPING.

Ejecuta pruebas previas al envío de forma implícita

Ejecuta pruebas previas al envío en archivos TEST_MAPPING en los directorios actual y principal:

atest

Ejecuta pruebas previas al envío en archivos TEST_MAPPING en /path/to/project y sus directorios superiores:

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

Ejecuta un grupo de prueba especificado

Los grupos de prueba disponibles son: presubmit(predeterminado), postsubmit, mainline-presubmit y all.

Ejecuta pruebas posteriores al envío en archivos TEST_MAPPING en los directorios actuales y superiores:

atest :postsubmit

Ejecuta pruebas de todos los grupos en los archivos TEST_MAPPING:

atest :all

Ejecuta pruebas posteriores al envío en archivos TEST_MAPPING en /path/to/project y sus directorios superiores:

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

Ejecuta pruebas de la línea principal en archivos TEST_MAPPING en /path/to/project y sus directorios principales:

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

Ejecuta pruebas en subdirectorios

De forma predeterminada, Atest solo busca pruebas en los archivos TEST_MAPPING hacia arriba (desde el directorio actual o el proporcionado hasta sus directorios superiores). Si también deseas ejecutar pruebas en archivos TEST_MAPPING en los subdirectorios, usa --include-subdirs para forzar a Atest a incluir también esas pruebas:

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

Ejecuta pruebas en la iteración

Ejecuta pruebas en iteraciones pasando el argumento --iterations. Ya sea que pase o falle, Atest repetirá la prueba hasta que se alcance la iteración máxima.

Ejemplos:

De forma predeterminada, Atest itera 10 veces. La cantidad de iteraciones debe ser un número entero positivo.

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

Los siguientes enfoques facilitan la detección de pruebas no confiables:

Enfoque 1: Ejecuta todas las pruebas hasta que se produzca una falla o se alcance la cantidad máxima de iteraciones.

  • Se detiene cuando se produce un error o la iteración alcanza la ronda número 10 (de forma predeterminada). 
    atest test-to-run --rerun-until-failure
  • Detenerse cuando se produzca un error o la iteración alcance la ronda número 100 
    atest test-to-run --rerun-until-failure 100

Enfoque 2: Ejecuta solo las pruebas fallidas hasta que se aprueben o se alcance la cantidad máxima de iteraciones.

  • Supongamos que test-to-run tiene varios casos de prueba y que una de las pruebas falla. Ejecuta solo la prueba fallida 10 veces (de forma predeterminada) o hasta que la prueba se apruebe. 
    atest test-to-run --retry-any-failure
  • Detén la ejecución de la prueba fallida cuando se apruebe o alcance la ronda número 100. 
    atest test-to-run --retry-any-failure 100

Ejecuta pruebas en AVD

Atest puede ejecutar pruebas en un AVD recién creado. Ejecuta acloud create para crear un AVD y artefactos de compilación, y, luego, usa los siguientes ejemplos para ejecutar tus pruebas.

Inicia un AVD y ejecuta pruebas en él:

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

Inicia un AVD como parte de una ejecución de prueba:

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

Ejecuta acloud create --help para obtener más información.

Cómo pasar opciones al módulo

Atest puede pasar opciones a los módulos de prueba. Para agregar opciones de línea de comandos de Tradefed a la ejecución de tu prueba, usa la siguiente estructura y asegúrate de que tus argumentos personalizados sigan el formato de las opciones de línea de comandos de Tradefed.

atest test-to-run -- [CUSTOM_ARGS]

Pasa opciones del módulo de prueba a los preparadores de destino o a los ejecutores de pruebas definidos en el archivo de configuración de la prueba:

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

Pasa opciones a un tipo o clase de ejecutor:

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 obtener más información sobre las opciones de solo prueba, consulta Cómo pasar opciones a los módulos.