Ejecutar pruebas (Atest)

Atest es una herramienta de línea de comandos que permite a los usuarios compilar, instalar y ejecutar pruebas de Android a nivel 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 la Federación de Comercio. 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 plataformas 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 de Atest Developer.

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 atestación tienen el siguiente formato:

atest test-to-run [optional-arguments]

Argumentos opcionales

En la siguiente tabla, se enumeran los argumentos más usados. Hay una lista completa disponible a través de atest --help.

Opción	Opción larga	Descripción
-b	--build	Compila destinos de prueba. (predeterminado)
-i	--install	Instala artefactos de prueba (APK) en el dispositivo. (predeterminado)
-t	--test	Ejecuta las pruebas. (predeterminado)
-s	--serial	Ejecuta las pruebas en el dispositivo especificado. Se puede probar un dispositivo a la vez.
-d	--disable-teardown	Inhabilita la limpieza y el desmontaje de pruebas.
	--dry-run	Ejecuta una prueba de Atest sin compilar, instalar ni ejecutar pruebas.
-m	--rebuild-module-info	Fuerza una nueva compilació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 alcanzar 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 iteración máxima. (10 de forma predeterminada)
	--retry-any-failure [COUNT=10]	Vuelve a ejecutar las pruebas que fallaron hasta que se aprueben o se alcance la iteración máxima. (10 de forma predeterminada)
	--start-avd	Crea un AVD automáticamente 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: Ejecutar una prueba de host que requiera un dispositivo con --host fallará.
	--history	Muestra los resultados de la prueba 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 Especifica los pasos: compila, instala o ejecuta.

Especifica pruebas

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

• Nombre del módulo
• Módulo:Clase
• 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, como en el siguiente ejemplo:

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 como aparece en las variables LOCAL_MODULE o LOCAL_PACKAGE_NAME del archivo Android.mk o Android.bp de esa prueba.

Ejemplos:

atest FrameworksServicesTests
atest CtsVideoTestCases

Nota: Para ejecutar pruebas que no sean de módulos integradas en TradeFed (TF), usa TF Integration Test como identificador.

Módulo:Clase

Para ejecutar una sola clase dentro de un módulo, usa Module:Class. Module es el mismo que se describe en Module name. 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

Nota: Para reducir el tiempo que tarda Atest en encontrar la prueba correcta, te recomendamos que uses la ruta de acceso completa de la clase, como se muestra en el último ejemplo.

Nombre de clase

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

Ejemplos:

atest ScreenDecorWindowTests
atest VideoEncoderDecoderTest

Nota: Para reducir el tiempo que tarda Atest en ubicar la prueba correcta, te recomendamos que uses Module:Class en lugar de solo el nombre de la clase siempre que sea posible.

Prueba de integración de Tradefed

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

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

atest example/reboot

Para ejecutar la prueba 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 en integraciones si ingresas 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 maneras de ejecutar el módulo CtsVideoTestCases con una ruta de acceso a un archivo.

Ejecuta desde Android repo-root:

atest cts/tests/video

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

    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 al archivo de 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: compila, instala o ejecuta

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

Nota: -b y -t se pueden ejecutar de forma individual, pero -i no se puede ejecutar sin -t.

• 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 a una prueba para que omita el paso de limpieza o desmontaje. Muchas pruebas, como CTS, limpian el dispositivo después de ejecutarla, por lo que intentar volver a ejecutar tu 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

Nota: Como -t inhabilita la configuración/instalación y la eliminación o limpieza del dispositivo, puedes volver a ejecutar la prueba con atest -t test-to-run tantas veces como desees.

Ejecuta 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 compatibles 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. Se prefiere usar estos ejemplos en lugar de solo usar el nombre de la clase, ya que especificar el módulo o la ubicación 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

Nota: Si solo necesitas ejecutar pruebas para una arquitectura de dispositivo específica, usa atest -- --abi arm64-v8a o atest -- --abi armeabi-v7a.

Si quieres seleccionar un objeto binario de GTest específico para ejecutar, usa dos puntos (:) para especificar el nombre de la prueba y un hashtag (#) para especificar un método individual.

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

TEST_F(InputDispatcherTest, InjectInputEvent_ValidatesKeyEvents)

Ejecuta lo siguiente para especificar toda la prueba:

atest inputflinger_tests:InputDispatcherTest

También puedes ejecutar una prueba individual con lo siguiente:

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 de envío previo en archivos TEST_MAPPING, en los directorios actuales y superiores:

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 los 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 los archivos TEST_MAPPING de /path/to/project y sus directorios superiores:

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

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

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 (del directorio actual o el directorio determinado a sus directorios superiores). Si también quieres ejecutar pruebas en archivos TEST_MAPPING en los subdirectorios, usa --include-subdirs para forzar a Atest a que también incluya esas pruebas:

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

Ejecutar pruebas de iteración

Para ejecutar pruebas en iteración, pasa el argumento --iterations. Ya sea que se apruebe 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 inestables:

Enfoque 1: Ejecuta todas las pruebas hasta que se produzca una falla o se alcance la iteración máxima.

• Se detiene cuando se produce una falla o cuando la iteración llega a la ronda 10 (de forma predeterminada).

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

• Se detiene cuando se produce una falla o la iteración llega a la ronda 100.

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

Enfoque 2: Ejecuta solo las pruebas que fallaron hasta que se aprueben o se alcance la iteración máxima.

• Supongamos que test-to-run tiene varios casos de prueba y uno de ellos falla. Ejecuta solo la prueba fallida 10 veces (de forma predeterminada) o hasta que esta se apruebe.

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

• Detén la ejecución de la prueba fallida cuando esta se apruebe o alcance la ronda 100.

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

Ejecuta pruebas en AVD

Atest puede ejecutar pruebas en un AVD creado recientemente. Ejecuta acloud create para crear un AVD y artefactos de compilación. 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"

Para obtener más información, ejecuta acloud create --help.

Nota: --acloud-create debe ser el ÚLTIMO argumento opcional. Cualquier argumento que lo siga se considerará un argumento posicional para el AVD.

Nota: --acloud-create y --start-avd no borran los AVD creados recientemente. Los usuarios deben borrarlas de forma manual.

Pasa opciones al módulo

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

atest test-to-run -- [CUSTOM_ARGS]

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

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.