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 supone que ya sabes cómo crear una aplicación para Android y escribir pruebas para tu app. Obtén más información sobre cómo compilar pruebas para tu app en 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, también puedes ejecutar las pruebas mediante un shell de Android Debug Bridge (adb).

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. Eso significa que, por ejemplo, puedes iniciar directamente 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 de manera adicional 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. A fin de ejecutar pruebas para un módulo específico del proyecto, agrega como prefijo de la prueba o la tarea connectedAndroidTest el nombre del módulo y dos puntos (:). 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 orientar pruebas específicas mediante 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'

Informes de varios módulos para pruebas instrumentadas

Como se describe en la Tabla 1, Gradle guarda los resultados de las pruebas instrumentadas en el directorio build/ de cada módulo que prueba. Sin embargo, si se ejecutan pruebas en varios módulos, podría resultar útil combinar todos los resultados en un único informe. Para generar un único informe cuando se ejecutan pruebas en varios módulos, sigue estos pasos:

  1. En el archivo build.gradle de nivel de proyecto, agrega lo siguiente después del bloque buildscript{}:

    Groovy

    apply plugin 'android-reporting'
    

    Kotlin

    apply(plugin = "android-reporting")
    
  2. Invoca la tarea test o connectedAndroidTest con la tarea mergeAndroidReports. Por ejemplo:

    ./gradlew connectedAndroidTest mergeAndroidReports
    

    Si deseas omitir las pruebas fallidas para que Gradle termine de ejecutar el resto de las pruebas, agrega la opción --continue:

    ./gradlew connectedAndroidTest mergeAndroidReports --continue
    

Cuando Gradle termina de ejecutar todas las pruebas, guarda los informes combinados en el directorio path_to_your_project/build/.

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 con ese 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 a fin de 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 package del elemento manifest correspondiente al archivo de manifiesto (AndroidManifest.xml) del paquete de prueba. Por lo general, la clase del ejecutor de pruebas de Android es AndroidJUnitRunner.

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

Los resultados de la prueba se muestran en STDOUT.

Marcas de am instrument

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

Tabla 2: Marcas de am instrument importantes.

Indicador Valor Descripción
-w (ninguno) Hace que am instrument espere hasta que finalice la instrumentación antes de terminar. El efecto neto es mantener el shell abierto hasta que hayan finalizado todas 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 marca -e perf true (que se documenta en la sección opciones de instrumento am).
-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 API ocultas. Para obtener más información sobre qué son las API 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 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/android.support.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 de clase de Java completamente calificado 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 completo de 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 también 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 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 (de forma separada) una clase dentro del paquete, Android ejecutará 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:
    • Foo1, que contiene el método de prueba bar1
    • Foo2, que contiene los métodos de prueba bar2 y bar3
  • 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/android.support.test.runner.AndroidJUnitRunner

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

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

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

Cómo seleccionar un subconjunto de pruebas

Para ejecutar todas las pruebas en la clase Foo1 y el método bar3 en Foo2, ingresa lo siguiente:

adb shell am instrument -w \
> -e class com.android.demo.app.tests.Foo1,com.android.demo.app.tests.Foo2#bar3 \
> com.android.demo.app.tests/android.support.test.runner.AndroidJUnitRunner

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