Cómo realizar pruebas desde la línea de comandos

En este documento, se describe cómo ejecutar pruebas directamente desde la línea de comandos. En este documento, se asume que ya sabes cómo crear una app para Android y cómo escribir pruebas para ella. Si quieres obtener más información sobre cómo compilar pruebas para tu app, consulta Cómo probar apps en Android.

Cuando compilas tu app con el sistema de compilación de Gradle, el complemento de Android para Gradle te permite ejecutar pruebas desde tu proyecto de Gradle mediante la línea de comandos. Si deseas obtener un control más detallado, puedes ejecutar las pruebas mediante un shell de Android Debug Bridge (adb). Esto puede ser útil cuando se ejecutan pruebas en un entorno de integración continua.

Si quieres obtener información para ejecutar pruebas instrumentadas automatizadas desde la línea de comandos con dispositivos virtuales que Gradle administra por ti, consulta el artículo Ajusta tus pruebas con dispositivos administrados por Gradle.

Cómo ejecutar pruebas con Gradle

El complemento de Android para Gradle te permite ejecutar pruebas desde tu proyecto de Gradle mediante la línea de comandos.

En la siguiente tabla, se resume cómo ejecutar pruebas con Gradle:

Tabla 1: Diferentes maneras de ejecutar tus pruebas con Gradle

Tipo de prueba de unidad Comando para ejecutar Ubicación del resultado de la prueba
Prueba de unidad local Ejecuta la tarea test: 

./gradlew test
Archivos de resultados de prueba HTML:
directorio path_to_your_project/module_name/build/reports/tests/.

Archivos de resultados de pruebas XML:
directorio path_to_your_project/module_name/build/test-results/.

Prueba de unidad instrumentada Ejecuta la tarea connectedAndroidTest: 

./gradlew connectedAndroidTest
Archivos de resultados de prueba HTML:
directorio path_to_your_project/module_name/build/reports/androidTests/connected/.

Archivos de resultados de pruebas XML:
directorio path_to_your_project/module_name/build/outputs/androidTest-results/connected/.

Gradle admite abreviaturas de nombres de tareas. Por ejemplo, puedes iniciar la tarea connectedAndroidTest con el siguiente comando:

./gradlew cAT

También puedes ejecutar las tareas de Gradle check y connectedCheck. Estas tareas ejecutan tus pruebas locales o instrumentadas, respectivamente, pero incluyen otras verificaciones agregadas por otros complementos de Gradle.

Cómo ejecutar pruebas en un módulo

Las tareas test y connectedAndroidTest ejecutan pruebas en cada módulo de tu proyecto. Puedes ejecutar pruebas en un módulo específico agregando el nombre del módulo y dos puntos (:) como prefijo de una tarea test o connectedAndroidTest. Por ejemplo, el siguiente comando ejecuta pruebas instrumentadas solo para el módulo mylibrary:

./gradlew mylibrary:connectedAndroidTest

Cómo ejecutar pruebas en una variante de compilación

Las tareas test y connectedAndroidTest ejecutan pruebas en cada variante de compilación de tu proyecto. También puedes orientar una variante de compilación específica mediante la siguiente sintaxis:

  • Para pruebas de unidades locales: 
    ./gradlew testVariantNameUnitTest
  • Para pruebas instrumentadas: 
    ./gradlew connectedVariantNameAndroidTest

Cómo ejecutar clases o métodos de prueba específicos

Cuando ejecutas pruebas de unidades locales, Gradle te permite segmentar pruebas específicas con la marca --tests. Por ejemplo, el siguiente comando ejecuta solo las pruebas de sampleTestMethod para la variante de compilación especificada. Para obtener más información sobre el uso de la marca --tests, consulta la documentación de Gradle sobre el filtrado de pruebas.


./gradlew testVariantNameUnitTest --tests '*.sampleTestMethod'

Cómo ejecutar pruebas con adb

Cuando se ejecutan pruebas desde la línea de comandos con Android Debug Bridge (adb), se obtienen más opciones para seleccionar las pruebas que se ejecutarán que con cualquier otro método. Puedes seleccionar métodos de prueba individuales, filtrar pruebas según una anotación personalizada o especificar opciones de prueba. Dado que la ejecución de pruebas se controla por completo desde la línea de comandos, puedes personalizar las pruebas con secuencias de comandos de shell de varias maneras.

Para ejecutar una prueba desde la línea de comandos, ejecuta adb shell para iniciar un shell de línea de comandos en el dispositivo o emulador. Dentro de ese shell, puedes interactuar con el administrador de actividades mediante el comando am y usar su subcomando instrument para ejecutar las pruebas.

A modo de atajo, puedes iniciar un shell de adb, llamar a am instrument y especificar funciones experimentales de línea de comandos, todo en una línea de entrada. Se abrirá el shell en el dispositivo o emulador, ejecutará las pruebas, generará el resultado y, luego, regresará a la línea de comandos de la computadora.

Para ejecutar una prueba con am instrument:

  1. Compila o vuelve a compilar la aplicación principal y el paquete de prueba.
  2. Instala los archivos del paquete de prueba y del paquete de Android de la aplicación principal (archivos APK) en el emulador o dispositivo de Android actual.

  3. En la línea de comandos, ingresa lo siguiente:

    adb shell am instrument -w <test_package_name>/<runner_class>

    Donde <test_package_name> es el nombre del paquete de Android de la aplicación de prueba, y <runner_class> es el nombre de la clase del ejecutor de pruebas de Android que estás usando. El nombre del paquete de Android es el valor del atributo del paquete del elemento del manifiesto que aparece en el archivo de manifiesto del paquete de prueba (AndroidManifest.xml).

    Por lo general, la clase del ejecutor de pruebas de Android es AndroidJUnitRunner:

    adb shell am instrument -w com.android.example/androidx.test.runner.AndroidJUnitRunner

Los resultados de la prueba se muestran en STDOUT.

Marcas de am instrument

Para ver la lista de todas las marcas para usar con el comando am instrument, ejecuta adb shell am help. En la siguiente tabla, se describen algunas marcas importantes:

Tabla 2: Marcas importantes am instrument

Marca Valor Descripción
-w (ninguno) Hace que am instrument espere hasta que finalice la instrumentación antes de terminar. Esto mantiene la shell abierta hasta que terminan las pruebas. Esta marca es obligatoria para ver los resultados de las pruebas.
-r (ninguno) Los resultados se generan en formato RAW. Usa esta marca cuando desees recopilar mediciones de rendimiento, de modo que no tengan el formato de los resultados de pruebas. Esta marca está diseñada para usarse junto con la sección de marca -e perf true (que se documenta en las Opciones de am instrument).
-e <test_options> Proporciona opciones de prueba como pares clave-valor. La herramienta am instrument pasa estos pares a la clase de instrumentación especificada mediante el método onCreate(). Puedes especificar varios casos de -e <test_options>. Las claves y los valores se describen en la sección Opciones de am instrument. Solo puedes usar estos pares clave-valor con AndroidJUnitRunner o con InstrumentationTestRunner y sus subclases. Si se usan con cualquier otra clase, no tendrán efecto.
--no-hidden-api-checks (ninguno) Inhabilita las restricciones de uso de APIs ocultas. Para obtener más información sobre qué son las APIs ocultas y cómo esto puede afectar tu app, consulta Restricciones en interfaces que no pertenecen al SDK.

Opciones de am instrument

La herramienta am instrument pasa las opciones de prueba a AndroidJUnitRunner o InstrumentationTestRunner en el formato de pares clave-valor, mediante la marca -e con la siguiente sintaxis: 

-e <key> <value>

Algunas claves aceptan múltiples valores. Debes especificar múltiples valores en una lista de valores separados por comas. Por ejemplo, esta invocación de AndroidJUnitRunner proporciona múltiples valores para la clave package:

adb shell am instrument -w -e package com.android.test.package1,com.android.test.package2 \
> com.android.test/androidx.test.runner.AndroidJUnitRunner

En la siguiente tabla, se muestran los pares clave-valor que puedes usar en el ejecutor de pruebas:

Tabla 3: Pares clave-valor de la marca -e para usar con el ejecutor de pruebas

Clave Valor Descripción
package <Java_package_name> Es el nombre completamente calificado del paquete Java correspondiente a uno de los paquetes de la aplicación de prueba. Se ejecutan todas las clases de caso de prueba que usan este nombre de paquete. Ten en cuenta que este no es un nombre de paquete de Android. Un paquete de prueba tiene un solo nombre de paquete de Android, pero puede contener varios paquetes de Java.
class <class_name> Es el nombre completamente calificado de la clase de Java correspondiente a una de las clases de caso de prueba. Solo se ejecuta esta clase de caso de prueba.
<class_name>#method name Es el nombre completamente calificado de la clase de caso de prueba y uno de los métodos. Solo se ejecuta este método. Ten en cuenta la marca de hash (#) entre el nombre de la clase y el nombre del método.
func true Ejecuta todas las clases de prueba que amplían InstrumentationTestCase.
unit true Ejecuta todas las clases de prueba que no amplían InstrumentationTestCase ni PerformanceTestCase.
size [small | medium | large] Ejecuta un método de prueba con anotación de tamaño. Las anotaciones son @SmallTest, @MediumTest y @LargeTest.
perf true Ejecuta todas las clases de prueba que implementan PerformanceTestCase. Si usas esta opción, especifica la marca -r para am instrument, de modo que se mantenga el resultado en formato RAW y que no se aplique el formato de resultados de prueba.
debug true Ejecuta pruebas en modo de depuración.
log true Carga y registra todas las pruebas especificadas, pero no las ejecuta. La información de pruebas aparece en STDOUT. Úsala para verificar las combinaciones de otros filtros y especificaciones de pruebas.
emma true Ejecuta un análisis de cobertura de código EMMA y escribe el resultado en el directorio /data/<app_package>/coverage.ec del dispositivo. Para anular la ubicación del archivo, usa la clave coverageFile que se describe en la siguiente entrada.

Nota: Esta opción requiere una compilación de la aplicación de prueba instrumentada por EMMA, que puedes generar con el objetivo coverage.

coverageFile <filename> Anula la ubicación predeterminada del archivo de cobertura de EMMA en el dispositivo. Especifica este valor como ruta de acceso y nombre de archivo en formato UNIX. El nombre de archivo predeterminado se describe en la entrada de la clave emma.

Cuando uses la marca -e, ten en cuenta lo siguiente:

  • am instrument invoca a onCreate(Bundle) con un Bundle que contiene los pares clave-valor.
  • La clave package tiene prioridad sobre la clave class. Si primero especificas un paquete, y luego una clase dentro del paquete por separado, Android ejecuta todas las pruebas del paquete y omitirá la clave de clase.
  • La claves func y unit son mutuamente excluyentes.

Ejemplos de uso

En las siguientes secciones, se proporcionan ejemplos de uso de am instrument para ejecutar pruebas. Los ejemplos se basan en la siguiente estructura:

  • El paquete de prueba tiene el nombre de paquete de Android com.android.demo.app.tests.
  • Dos clases de prueba instrumentada:
    • TestClass1, que contiene el método de prueba testMethod1.
    • TestClass2, que contiene los métodos de prueba testMethod2 y testMethod3.
  • El ejecutor de pruebas es AndroidJUnitRunner.

Cómo ejecutar el paquete de prueba completo

Para ejecutar todas las clases de prueba en el paquete de prueba, ingresa:

adb shell am instrument -w com.android.demo.app.tests/androidx.test.runner.AndroidJUnitRunner

Cómo ejecutar todas las pruebas en una clase de caso de prueba

Para ejecutar todas las pruebas de la clase TestClass1, ingresa lo siguiente:

adb shell am instrument -w  \
> -e class com.android.demo.app.tests.TestClass1 \
> com.android.demo.app.tests/androidx.test.runner.AndroidJUnitRunner

Cómo seleccionar un subconjunto de pruebas

Para ejecutar todas las pruebas en la clase TestClass1 y el método testMethod3 en TestClass2, ingresa lo siguiente:

adb shell am instrument -w \
> -e class com.android.demo.app.tests.TestClass1,com.android.demo.app.tests.TestClass2#testMethod3 \
> com.android.demo.app.tests/androidx.test.runner.AndroidJUnitRunner

Puedes encontrar más casos de uso en la referencia de la API de AndroidJUnitRunner.