Cómo escribir pruebas automatizadas con UI Automator

UI Automator es un framework de prueba de la IU adecuado para las pruebas funcionales de IU entre apps en 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é en primer plano, de modo que te permite realizar operaciones como abrir el menú Configuración o el selector de aplicaciones en un dispositivo de prueba. La prueba puede buscar un componente de IU mediante descriptores convenientes, 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 de 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:

  • Una API para recuperar información de estado y realizar operaciones en el dispositivo de destino. Para obtener más información, consulta Cómo acceder al estado del dispositivo.
  • API compatibles con pruebas de IU entre apps. Para obtener más información, consulta las APIs 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 que se ejecuta la 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. Presiona las teclas de hardware, por ejemplo, "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 presión de un botón de inicio, llama al método UiDevice.pressHome().

API de UI Automator

Las APIs de UI Automator te permiten escribir pruebas sólidas sin necesidad de conocer los detalles de implementación de la app a la que te orientas. 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 que coincidan los elementos de la IU.
  • By: Construye BySelector de manera concisa.
  • Configurator: Te permite establecer parámetros clave para ejecutar pruebas de UI Automator.

Por ejemplo, el siguiente código muestra cómo puedes 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-alpha03')
}

Groovy

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

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, comprueba que los componentes tengan etiquetas de texto visibles, valores de android:contentDescription o ambos.

La herramienta uiautomatorviewer proporciona una interfaz visual conveniente para inspeccionar la jerarquía de diseño y ver las propiedades de los componentes de la IU que están visibles en el primer plano del dispositivo. Esta información te permite crear pruebas más detalladas 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. Coloca el cursor sobre la instantánea en el panel izquierdo para ver los componentes de la IU identificados por la herramienta uiautomatorviewer. Las propiedades se enumeran en el panel inferior derecho y la jerarquía de diseño en el panel superior derecho.
  3. De manera opcional, haz 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 tiene un mejor rendimiento en las apps que tienen funciones de accesibilidad de Android implementadas. Cuando usas elementos de la IU de tipo View o una subclase de View del SDK, no necesitas implementar la compatibilidad de accesibilidad, dado que estas clases ya lo hicieron por ti.

Sin embargo, algunas apps usan elementos de IU personalizados para brindar 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 pertenece al SDK, asegúrate de agregar funciones de accesibilidad a estos elementos completando los siguientes pasos:

  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 orientación adicional 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 debe escribirse de la misma manera que una clase de prueba 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 ejecutor de pruebas 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 quieras 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 para probar interacciones del usuario más complejas que involucren varios componentes de la IU o secuencias de acciones del usuario.
  4. Comprueba que la IU refleje el estado o el comportamiento esperados después de que se realicen estas interacciones del usuario.

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 tus 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 puede obtener una instancia de UiDevice y simular que se presiona 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 declaración @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 hayas creado en otras partes de las pruebas de tu 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 puede construir instancias de UiObject2 que representen un botón Cancel 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 IU específico en una app, usa la clase By para construir una instancia de BySelector. BySelector representa una consulta para elementos específicos de la IU que se muestra.

Si se encuentra más de un elemento coincidente, el primer elemento coincidente en la jerarquía de diseño se muestra como UiObject2 de destino. Cuando construyes 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 null.

Puedes usar el método hasChild() o hasDescendant() para anidar varias instancias de BySelector. En el siguiente ejemplo de código, se muestra la manera en que la prueba podría especificar una búsqueda para encontrar el primer ListView que tiene un elemento de IU secundario 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 que puedas desmarcarlos, llama al método checked() con el argumento establecido en verdadero.

Realizar acciones

Una vez que la prueba haya obtenido un objeto UiObject2, puedes llamar a los métodos de la clase UiObject2 para realizar interacciones del usuario en el componente de IU representado por 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() : Realiza la acción de deslizar hacia la dirección especificada.
  • scrollUntil(): Realiza la acción de desplazamiento hacia la dirección especificada hasta que se cumplen Condition o EventCondition.

El framework de prueba de UI Automator te permite enviar un Intent o iniciar una Activity 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 que se está probando. Este enfoque es útil cuando solo te interesa probar la app de la calculadora y no te interesa 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 los métodos Assert estándares de JUnit para probar que los componentes de la IU de 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 en orden y, luego, verificar que se muestre 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 ejecutor de instrumentación predeterminado en tu proyecto.

Más ejemplos

Cómo interactuar con la IU del sistema

UI Automator puede interactuar con todo el contenido de la pantalla, incluidos los elementos del sistema fuera de la 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

Desactivar interrumpir
Figura 1. UI Automator desactiva el modo No interrumpir en un dispositivo de prueba.

Las transiciones de pantalla pueden llevar tiempo y la predicción de su duración no es confiable, por lo que debes hacer que UI Automator espere después de realizar las operaciones. UI Automator proporciona varios métodos para hacerlo:

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 las 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