Cómo escribir pruebas automatizadas con UI Automator

UI Automator es un framework de prueba de la IU adecuado para pruebas funcionales de IU entre aplicaciones en todo el sistema y en apps instaladas. Las APIs de UI Automator te permiten interactuar con elementos visibles en un dispositivo, independientemente de qué Activity esté enfocada, por lo que te permiten realizar operaciones como abrir el menú Configuración o el selector de apps en un dispositivo de prueba. La prueba puede buscar un componente de la IU mediante descriptores adecuados, como el texto que se muestra en ese componente o su descripción de contenido.

El framework de prueba de UI Automator es una API basada en instrumentación que funciona con el ejecutor de pruebas AndroidJUnitRunner. Es adecuado para escribir pruebas automatizadas de estilo "caja opaca", en las que el código de prueba no se basa en detalles de implementación internos de la app de destino.

Estas son algunas de las funciones clave del framework de prueba de UI Automator:

Cómo acceder al estado del dispositivo

El framework de prueba de UI Automator proporciona una clase UiDevice para acceder al dispositivo en el cual se ejecuta una app de destino y realizar operaciones en él. Puedes llamar a sus métodos para acceder a las propiedades del dispositivo, como la orientación o el tamaño de pantalla actuales. La clase UiDevice también te permite realizar las siguientes acciones:

  1. Cambiar la rotación del dispositivo.
  2. Presionar teclas de hardware, como "subir volumen".
  3. Presionar los botones Atrás, Página principal o Menú.
  4. Abrir el panel de notificaciones.
  5. Tomar una captura de pantalla de la ventana actual.

Por ejemplo, para simular la acción de presionar del botón de inicio, llama al método UiDevice.pressHome().

API de UI Automator

Las APIs de UI Automator te permiten escribir pruebas eficaces sin necesidad de conocer detalles sobre la implementación de la app a la que apuntas. Puedes usar estas APIs para capturar y manipular los componentes de la IU en varias apps:

  • UiObject2: Representa un elemento de la IU que es visible en el dispositivo.
  • BySelector: Especifica los criterios para hacer coincidir los elementos de la IU.
  • By: Construye BySelector de forma concisa.
  • Configurator: Te permite establecer parámetros clave para ejecutar pruebas de UI Automator.

Por ejemplo, en el siguiente código, se muestra cómo escribir una secuencia de comandos de prueba que abre una app de Gmail en el dispositivo:

Kotlin

device = UiDevice.getInstance(InstrumentationRegistry.getInstrumentation())
device.pressHome()

val gmail: UiObject2 = device.findObject(By.text("Gmail"))
// Perform a click and wait until the app is opened.
val opened: Boolean = gmail.clickAndWait(Until.newWindow(), 3000)
assertThat(opened).isTrue()

Java

device = UiDevice.getInstance(InstrumentationRegistry.getInstrumentation());
device.pressHome();

UiObject2 gmail = device.findObject(By.text("Gmail"));
// Perform a click and wait until the app is opened.
Boolean opened = gmail.clickAndWait(Until.newWindow(), 3000);
assertTrue(opened);

Cómo configurar UI Automator

Antes de compilar la prueba de la IU con UI Automator, asegúrate de configurar la ubicación del código fuente de prueba y las dependencias del proyecto, como se describe en Cómo configurar el proyecto para AndroidX Test.

En el archivo build.gradle del módulo de tu app para Android, debes establecer una referencia de dependencia a la biblioteca de UI Automator:

Kotlin

dependencies {
  ...
  androidTestImplementation("androidx.test.uiautomator:uiautomator:2.3.0")
}

Groovy

dependencies {
  ...
  androidTestImplementation 'androidx.test.uiautomator:uiautomator:2.3.0'
}

Para optimizar las pruebas de UI Automator, primero debes inspeccionar los componentes de la IU de la app de destino y asegurarte de que se pueda acceder a ellos. Estas sugerencias de optimización se describen en las siguientes dos secciones.

Cómo inspeccionar la IU en un dispositivo

Antes de diseñar la prueba, inspecciona los componentes de la IU que son visibles en el dispositivo. Para asegurarte de que las pruebas de UI Automator puedan acceder a estos componentes, verifica que tengan etiquetas de texto visibles, valores de android:contentDescription o ambos.

La herramienta uiautomatorviewer proporciona una interfaz visual práctica para inspeccionar la jerarquía de diseño y ver las propiedades de los componentes de la IU que son visibles en primer plano en el dispositivo. Esta información te permite crear pruebas más específicas mediante UI Automator. Por ejemplo, puedes crear un selector de IU que coincida con una propiedad visible específica.

Para iniciar la herramienta uiautomatorviewer, haz lo siguiente:

  1. Inicia la app de destino en un dispositivo físico.
  2. Conecta el dispositivo a la máquina de desarrollo.
  3. Abre una ventana de terminal y navega al directorio <android-sdk>/tools/.
  4. Ejecuta la herramienta con este comando:
 $ uiautomatorviewer

Para ver las propiedades de la IU de tu aplicación, haz lo siguiente:

  1. En la interfaz de uiautomatorviewer, haz clic en el botón Device Screenshot.
  2. Desplázate sobre la instantánea en el panel de la izquierda para ver los componentes de la IU identificados por la herramienta uiautomatorviewer. Las propiedades se muestran en el panel inferior derecho y la jerarquía de diseño, en el panel superior derecho.
  3. Opcionalmente, puedes hacer clic en el botón Toggle NAF Nodes para ver los componentes de la IU a los que no puede acceder UI Automator. Es posible que solo haya información limitada disponible para estos componentes.

Para obtener información sobre los tipos comunes de componentes de la IU proporcionados por Android, consulta Interfaz de usuario.

Asegúrate de que se pueda acceder a tu actividad

El framework de prueba de UI Automator brinda un mejor rendimiento en apps que tienen funciones de accesibilidad de Android implementadas. Cuando usas elementos de IU del tipo View o una subclase de View del SDK, no necesitas implementar la compatibilidad de accesibilidad, ya que esas clases lo hacen por ti.

Sin embargo, algunas apps usan elementos de IU personalizados para proporcionar una experiencia del usuario enriquecida. Estos elementos no proporcionarán compatibilidad de accesibilidad automática. Si tu app contiene instancias de una subclase de View que no es del SDK, sigue los pasos que se indican a continuación para asegurarte de agregar funciones de accesibilidad a estos elementos:

  1. Crea una clase concreta que extienda ExploreByTouchHelper.
  2. Asocia una instancia de tu nueva clase con un elemento de IU personalizado específico llamando a setAccessibilityDelegate().

Para obtener más información sobre cómo agregar funciones de accesibilidad a los elementos de vista personalizada, consulta Cómo compilar vistas personalizadas accesibles. Para obtener más información sobre las prácticas recomendadas generales de accesibilidad en Android, consulta Cómo crear apps más accesibles.

Cómo crear una clase de prueba de UI Automator

La clase de prueba de UI Automator se debe escribir de la misma manera que una clase de prueba de JUnit 4. Para obtener más información sobre la creación de clases de prueba de JUnit 4 y el uso de aserciones y anotaciones de JUnit 4, consulta Cómo crear una clase de prueba de unidades instrumentada.

Agrega la anotación @RunWith(AndroidJUnit4.class) al comienzo de la definición de la clase de prueba. También debes especificar la clase AndroidJUnitRunner, proporcionada en AndroidX Test, como el panel de prueba predeterminado. Este paso se describe con más detalle en Cómo ejecutar pruebas de UI Automator en un dispositivo o emulador.

Implementa el siguiente modelo de programación en la clase de prueba de UI Automator:

  1. Obtén un objeto UiDevice para acceder al dispositivo que deseas probar llamando al método getInstance() y pasándole un objeto Instrumentation como argumento.
  2. Obtén un objeto UiObject2 para acceder a un componente de la IU que se muestra en el dispositivo (por ejemplo, la vista actual en primer plano) llamando al método findObject().
  3. Llama a un método UiObject2 para simular una interacción específica del usuario que se realizará en ese componente de la IU. Por ejemplo, llama a scrollUntil() para desplazarte y a setText() para editar un campo de texto. Puedes llamar a las APIs de los pasos 2 y 3 repetidamente según sea necesario, con el fin de probar interacciones de usuario más complejas que involucren varios componentes de la IU o secuencias de acciones del usuario.
  4. Después de que se realicen estas interacciones del usuario, comprueba si la IU refleja el estado o el comportamiento esperados.

Estos pasos se explican con más detalles en las siguientes secciones.

Cómo acceder a los componentes de la IU

El objeto UiDevice es la forma principal de acceder al estado del dispositivo y manipularlo. En las pruebas, puedes llamar a los métodos UiDevice para comprobar el estado de varias propiedades, como la orientación actual o el tamaño de la pantalla. La prueba puede usar el objeto UiDevice para realizar acciones a nivel del dispositivo, como forzar una rotación específica del dispositivo, presionar botones de hardware del pad direccional y presionar los botones de Inicio y Menú.

Se recomienda comenzar la prueba desde la pantalla principal del dispositivo. Desde la pantalla principal (o alguna otra ubicación de inicio que hayas elegido en el dispositivo), puedes llamar a los métodos proporcionados por la API de UI Automator para seleccionar elementos específicos de la IU e interactuar con ellos.

En el siguiente fragmento de código, se muestra cómo la prueba podría obtener una instancia de UiDevice y simular la acción de presionar el botón de inicio:

Kotlin

import org.junit.Before
import androidx.test.runner.AndroidJUnit4
import androidx.test.uiautomator.UiDevice
import androidx.test.uiautomator.By
import androidx.test.uiautomator.Until
...

private const val BASIC_SAMPLE_PACKAGE = "com.example.android.testing.uiautomator.BasicSample"
private const val LAUNCH_TIMEOUT = 5000L
private const val STRING_TO_BE_TYPED = "UiAutomator"

@RunWith(AndroidJUnit4::class)
@SdkSuppress(minSdkVersion = 18)
class ChangeTextBehaviorTest2 {

private lateinit var device: UiDevice

@Before
fun startMainActivityFromHomeScreen() {
  // Initialize UiDevice instance
  device = UiDevice.getInstance(InstrumentationRegistry.getInstrumentation())

  // Start from the home screen
  device.pressHome()

  // Wait for launcher
  val launcherPackage: String = device.launcherPackageName
  assertThat(launcherPackage, notNullValue())
  device.wait(
    Until.hasObject(By.pkg(launcherPackage).depth(0)),
    LAUNCH_TIMEOUT
  )

  // Launch the app
  val context = ApplicationProvider.getApplicationContext<Context>()
  val intent = context.packageManager.getLaunchIntentForPackage(
  BASIC_SAMPLE_PACKAGE).apply {
    // Clear out any previous instances
    addFlags(Intent.FLAG_ACTIVITY_CLEAR_TASK)
  }
  context.startActivity(intent)

  // Wait for the app to appear
  device.wait(
    Until.hasObject(By.pkg(BASIC_SAMPLE_PACKAGE).depth(0)),
    LAUNCH_TIMEOUT
    )
  }
}

Java

import org.junit.Before;
import androidx.test.runner.AndroidJUnit4;
import androidx.test.uiautomator.UiDevice;
import androidx.test.uiautomator.By;
import androidx.test.uiautomator.Until;
...

@RunWith(AndroidJUnit4.class)
@SdkSuppress(minSdkVersion = 18)
public class ChangeTextBehaviorTest {

  private static final String BASIC_SAMPLE_PACKAGE
  = "com.example.android.testing.uiautomator.BasicSample";
  private static final int LAUNCH_TIMEOUT = 5000;
  private static final String STRING_TO_BE_TYPED = "UiAutomator";
  private UiDevice device;

  @Before
  public void startMainActivityFromHomeScreen() {
    // Initialize UiDevice instance
    device = UiDevice.getInstance(InstrumentationRegistry.getInstrumentation());

    // Start from the home screen
    device.pressHome();

    // Wait for launcher
    final String launcherPackage = device.getLauncherPackageName();
    assertThat(launcherPackage, notNullValue());
    device.wait(Until.hasObject(By.pkg(launcherPackage).depth(0)),
    LAUNCH_TIMEOUT);

    // Launch the app
    Context context = ApplicationProvider.getApplicationContext();
    final Intent intent = context.getPackageManager()
    .getLaunchIntentForPackage(BASIC_SAMPLE_PACKAGE);
    // Clear out any previous instances
    intent.addFlags(Intent.FLAG_ACTIVITY_CLEAR_TASK);
    context.startActivity(intent);

    // Wait for the app to appear
    device.wait(Until.hasObject(By.pkg(BASIC_SAMPLE_PACKAGE).depth(0)),
    LAUNCH_TIMEOUT);
    }
}

En el ejemplo, la sentencia @SdkSuppress(minSdkVersion = 18) ayuda a garantizar que las pruebas solo se ejecuten en dispositivos con Android 4.3 (nivel de API 18) o versiones posteriores, según lo requiera el framework de UI Automator.

Usa el método findObject() para recuperar un UiObject2 que represente una vista que coincida con un criterio de selección determinado. Puedes volver a usar las instancias de UiObject2 que creaste en otras partes de la prueba de la app, según sea necesario. Ten en cuenta que el framework de prueba de UI Automator busca una coincidencia en la pantalla actual cada vez que la prueba usa una instancia de UiObject2 para hacer clic en un elemento de la IU o consultar una propiedad.

En el siguiente fragmento, se muestra cómo la prueba podría crear instancias de UiObject2 que representen un botón Cancelar y un botón Aceptar en una app.

Kotlin

val okButton: UiObject2 = device.findObject(
    By.text("OK").clazz("android.widget.Button")
)

// Simulate a user-click on the OK button, if found.
if (okButton != null) {
    okButton.click()
}

Java

UiObject2 okButton = device.findObject(
    By.text("OK").clazz("android.widget.Button")
);

// Simulate a user-click on the OK button, if found.
if (okButton != null) {
    okButton.click();
}

Cómo especificar un selector

Si quieres acceder a un componente de la IU específico en una app, usa la clase By para crear una instancia de BySelector. BySelector representa una consulta de elementos específicos de la IU que se muestra.

Si se encuentra más de un elemento coincidente, el primero de la jerarquía de diseño se mostrará como el UiObject2 de destino. Cuando creas un BySelector, puedes encadenar varias propiedades para definir mejor la búsqueda. Si no se encuentra ningún elemento de IU que coincida, se muestra un null.

Puedes usar el método hasChild() o hasDescendant() para anidar varias instancias de BySelector. Por ejemplo, en el siguiente ejemplo de código, se muestra cómo tu prueba podría especificar una búsqueda para encontrar el primer ListView que tenga un elemento secundario de la IU con la propiedad de texto.

Kotlin

val listView: UiObject2 = device.findObject(
    By.clazz("android.widget.ListView")
        .hasChild(
            By.text("Apps")
        )
)

Java

UiObject2 listView = device.findObject(
    By.clazz("android.widget.ListView")
        .hasChild(
            By.text("Apps")
        )
);

Puede ser útil especificar el estado del objeto en los criterios del selector. Por ejemplo, si deseas seleccionar una lista de todos los elementos marcados para desmarcarlos, llama al método checked() con el argumento establecido en "true".

Realizar acciones

Una vez que la prueba haya obtenido un objeto UiObject2, puedes llamar a los métodos de la clase UiObject2 para ejecutar interacciones del usuario en el componente de IU que representa ese objeto. Puedes especificar acciones como las siguientes:

  • click() : Hace clic en el centro de los límites visibles del elemento de la IU.
  • drag() : Arrastra este objeto a coordenadas arbitrarias.
  • setText() : Establece el texto en un campo editable después de borrar el contenido del campo. Por el contrario, el método clear() borra el texto existente en un campo editable.
  • swipe() : Ejecuta la acción de deslizar hacia la dirección especificada.
  • scrollUntil(): Ejecuta la acción de desplazamiento hacia la dirección especificada hasta que se cumpla Condition o EventCondition.

El framework de prueba de UI Automator te permite enviar un intent o iniciar una actividad sin usar comandos de shell mediante la obtención de un objeto Context a través de getContext().

En el siguiente fragmento, se muestra cómo la prueba puede usar un Intent para iniciar la app en modo de prueba. Este enfoque es útil si solo te interesa probar la app de la calculadora y no el selector.

Kotlin

fun setUp() {
...

  // Launch a simple calculator app
  val context = getInstrumentation().context
  val intent = context.packageManager.getLaunchIntentForPackage(CALC_PACKAGE).apply {
    addFlags(Intent.FLAG_ACTIVITY_CLEAR_TASK)
  }
  // Clear out any previous instances
  context.startActivity(intent)
  device.wait(Until.hasObject(By.pkg(CALC_PACKAGE).depth(0)), TIMEOUT)
}

Java

public void setUp() {
...

  // Launch a simple calculator app
  Context context = getInstrumentation().getContext();
  Intent intent = context.getPackageManager()
  .getLaunchIntentForPackage(CALC_PACKAGE);
  intent.addFlags(Intent.FLAG_ACTIVITY_CLEAR_TASK);

  // Clear out any previous instances
  context.startActivity(intent);
  device.wait(Until.hasObject(By.pkg(CALC_PACKAGE).depth(0)), TIMEOUT);
}

Cómo verificar los resultados

InstrumentationTestCase extiende TestCase, por lo que puedes usar métodos Assert estándar de JUnit para probar que los componentes de la IU en la app muestren los resultados esperados.

En el siguiente fragmento, se muestra cómo la prueba puede ubicar varios botones en una app de calculadora, hacer clic en ellos por orden y luego verificar que se muestra el resultado correcto.

Kotlin

private const val CALC_PACKAGE = "com.myexample.calc"

fun testTwoPlusThreeEqualsFive() {
  // Enter an equation: 2 + 3 = ?
  device.findObject(By.res(CALC_PACKAGE, "two")).click()
  device.findObject(By.res(CALC_PACKAGE, "plus")).click()
  device.findObject(By.res(CALC_PACKAGE, "three")).click()
  device.findObject(By.res(CALC_PACKAGE, "equals")).click()

  // Verify the result = 5
  val result: UiObject2 = device.findObject(By.res(CALC_PACKAGE, "result"))
  assertEquals("5", result.text)
}

Java

private static final String CALC_PACKAGE = "com.myexample.calc";

public void testTwoPlusThreeEqualsFive() {
  // Enter an equation: 2 + 3 = ?
  device.findObject(By.res(CALC_PACKAGE, "two")).click();
  device.findObject(By.res(CALC_PACKAGE, "plus")).click();
  device.findObject(By.res(CALC_PACKAGE, "three")).click();
  device.findObject(By.res(CALC_PACKAGE, "equals")).click();

  // Verify the result = 5
  UiObject2 result = device.findObject(By.res(CALC_PACKAGE, "result"));
  assertEquals("5", result.getText());
}

Cómo ejecutar pruebas de UI Automator en un dispositivo o emulador

Puedes ejecutar pruebas de UI Automator desde Android Studio o desde la línea de comandos. Asegúrate de especificar AndroidJUnitRunner como el comparador de instrumentación predeterminado en tu proyecto.

Más ejemplos

Cómo interactuar con la IU del sistema

UI Automator puede interactuar con todo lo que aparece en la pantalla, incluidos los elementos del sistema fuera de tu app, como se muestra en los siguientes fragmentos de código:

Kotlin

// Opens the System Settings.
device = UiDevice.getInstance(InstrumentationRegistry.getInstrumentation())
device.executeShellCommand("am start -a android.settings.SETTINGS")

Java

// Opens the System Settings.
device = UiDevice.getInstance(InstrumentationRegistry.getInstrumentation());
device.executeShellCommand("am start -a android.settings.SETTINGS");

Kotlin

// Opens the notification shade.
device = UiDevice.getInstance(InstrumentationRegistry.getInstrumentation())
device.openNotification()

Java

// Opens the notification shade.
device = UiDevice.getInstance(InstrumentationRegistry.getInstrumentation());
device.openNotification();

Kotlin

// Opens the Quick Settings shade.
device = UiDevice.getInstance(InstrumentationRegistry.getInstrumentation())
device.openQuickSettings()

Java

// Opens the Quick Settings shade.
device = UiDevice.getInstance(InstrumentationRegistry.getInstrumentation());
device.openQuickSettings();

Kotlin

// Get the system clock.
device = UiDevice.getInstance(InstrumentationRegistry.getInstrumentation())
UiObject2 clock = device.findObject(By.res("com.android.systemui:id/clock"))
print(clock.getText())

Java

// Get the system clock.
device = UiDevice.getInstance(InstrumentationRegistry.getInstrumentation());
UiObject2 clock = device.findObject(By.res("com.android.systemui:id/clock"));
print(clock.getText());

Espera las transiciones

Cómo desactivar No interrumpir
Figura 1: UI Automator desactiva el modo No interrumpir en un dispositivo de prueba.

Las transiciones de pantalla pueden tardar un tiempo, y predecir su duración no es confiable, por lo que debes hacer que UI Automator espere después de realizar operaciones. UI Automator proporciona varios métodos para esto:

En el siguiente fragmento de código, se muestra cómo usar UI Automator para desactivar el modo No interrumpir en la configuración del sistema con el método performActionAndWait() que espera transiciones:

Kotlin

@Test
@SdkSuppress(minSdkVersion = 21)
@Throws(Exception::class)
fun turnOffDoNotDisturb() {
    device = UiDevice.getInstance(InstrumentationRegistry.getInstrumentation())
    device.performActionAndWait({
        try {
            device.executeShellCommand("am start -a android.settings.SETTINGS")
        } catch (e: IOException) {
            throw RuntimeException(e)
        }
    }, Until.newWindow(), 1000)
    // Check system settings has been opened.
    Assert.assertTrue(device.hasObject(By.pkg("com.android.settings")))

    // Scroll the settings to the top and find Notifications button
    var scrollableObj: UiObject2 = device.findObject(By.scrollable(true))
    scrollableObj.scrollUntil(Direction.UP, Until.scrollFinished(Direction.UP))
    val notificationsButton = scrollableObj.findObject(By.text("Notifications"))

    // Click the Notifications button and wait until a new window is opened.
    device.performActionAndWait({ notificationsButton.click() }, Until.newWindow(), 1000)
    scrollableObj = device.findObject(By.scrollable(true))
    // Scroll down until it finds a Do Not Disturb button.
    val doNotDisturb = scrollableObj.scrollUntil(
        Direction.DOWN,
        Until.findObject(By.textContains("Do Not Disturb"))
    )
    device.performActionAndWait({ doNotDisturb.click() }, Until.newWindow(), 1000)
    // Turn off the Do Not Disturb.
    val turnOnDoNotDisturb = device.findObject(By.text("Turn on now"))
    turnOnDoNotDisturb?.click()
    Assert.assertTrue(device.wait(Until.hasObject(By.text("Turn off now")), 1000))
}

Java

@Test
@SdkSuppress(minSdkVersion = 21)
public void turnOffDoNotDisturb() throws Exception{
    device = UiDevice.getInstance(InstrumentationRegistry.getInstrumentation());
    device.performActionAndWait(() -> {
        try {
            device.executeShellCommand("am start -a android.settings.SETTINGS");
        } catch (IOException e) {
            throw new RuntimeException(e);
        }
    }, Until.newWindow(), 1000);
    // Check system settings has been opened.
    assertTrue(device.hasObject(By.pkg("com.android.settings")));

    // Scroll the settings to the top and find Notifications button
    UiObject2 scrollableObj = device.findObject(By.scrollable(true));
    scrollableObj.scrollUntil(Direction.UP, Until.scrollFinished(Direction.UP));
    UiObject2 notificationsButton = scrollableObj.findObject(By.text("Notifications"));

    // Click the Notifications button and wait until a new window is opened.
    device.performActionAndWait(() -> notificationsButton.click(), Until.newWindow(), 1000);
    scrollableObj = device.findObject(By.scrollable(true));
    // Scroll down until it finds a Do Not Disturb button.
    UiObject2 doNotDisturb = scrollableObj.scrollUntil(Direction.DOWN,
            Until.findObject(By.textContains("Do Not Disturb")));
    device.performActionAndWait(()-> doNotDisturb.click(), Until.newWindow(), 1000);
    // Turn off the Do Not Disturb.
    UiObject2 turnOnDoNotDisturb = device.findObject(By.text("Turn on now"));
    if(turnOnDoNotDisturb != null) {
        turnOnDoNotDisturb.click();
    }
    assertTrue(device.wait(Until.hasObject(By.text("Turn off now")), 1000));
}

Recursos adicionales

Para obtener más información sobre el uso de UI Automator en las pruebas de Android, consulta los siguientes recursos.

Documentación de referencia:

Ejemplos