Detox: qué es, cómo funciona y pruebas E2E

Qué es Detox

Detox es un framework para pruebas de extremo a extremo (E2E) de aplicaciones móviles, desarrollado por Wix en 2017. Está diseñado para proyectos React Native, pero también soporta aplicaciones puramente nativas en iOS y Android. Detox funciona con un modelo gray-box, lo que significa que tiene acceso a los mecanismos internos de la aplicación.

Diferencia de otros frameworks E2E

La principal diferencia entre Detox y Appium o Calabash es la sincronización automática con la aplicación. El framework espera a que se completen las animaciones, las solicitudes de red y el procesamiento de eventos antes de ejecutar la siguiente acción. Esto elimina por completo la necesidad de Thread.sleep() o waitForElement, que ralentizan las pruebas.

Plataformas soportadas

Detox soporta iOS (a través de XCTest y Xcode) y Android (a través de Espresso y UI Automator). Para aplicaciones React Native, se proporciona soporte completo para Fabric y la arquitectura antigua. En iOS, las pruebas se ejecutan en el simulador; en Android, en el emulador o en un dispositivo real.

Arquitectura de Detox y modelo gray-box

La arquitectura de Detox consta de tres componentes clave: Detox CLI, el ejecutor de pruebas Detox y Detox Native Driver. Detox CLI gestiona la compilación, instalación y ejecución de pruebas de la aplicación. El ejecutor de pruebas (Jest o Mocha) ejecuta los escenarios de prueba y se comunica con la aplicación a través de WebSocket.

Enfoque gray-box

Las pruebas gray-box significan que Detox tiene acceso al estado interno de la aplicación a través de un puente nativo. El framework monitorea las solicitudes de red, animaciones, temporizadores y la cola de operaciones. Cuando todas las colas están vacías, Detox considera que la aplicación está lista para el siguiente paso.

Mecanismo de sincronización

La sincronización se basa en el monitoreo del hilo principal de la aplicación. Detox espera hasta que todas las animaciones se completen, las solicitudes HTTP devuelvan respuestas y los manejadores de eventos terminen de ejecutarse. Si una prueba se bloquea debido a una animación infinita, se puede deshabilitar manualmente la sincronización para un bloque de código específico.

// Deshabilitar la sincronización para una sección problemática
await device.disableSynchronization();
// Acción con animación larga
await element(by.id('loader')).swipe('down');
await device.enableSynchronization();

Instalación y configuración de Detox

La instalación de Detox comienza añadiendo el paquete a través de npm o yarn. Después de la instalación, es necesario crear un archivo de configuración .detoxrc.js, que describe las opciones de compilación y ejecución para cada plataforma. Detox utiliza su propio tipo de compilación para iOS, basado en la configuración de Xcode.

Configuración básica

La configuración incluye la ruta a la aplicación (app), el tipo de compilador (build), los argumentos de compilación y la configuración del dispositivo (device). Para iOS se utiliza appleSimulator, para Android androidEmulator. También se pueden especificar argumentos de inicio como el idioma o la región del simulador.

// .detoxrc.js — ejemplo de configuración
module.exports = {
  testRunner: { args: { '$0': 'jest', config: 'e2e/config.json' } },
  apps: {
    'ios.debug': { type: 'ios.app', build: 'xcodebuild ...' },
    'android.debug': { type: 'android.apk', build: 'cd android && ./gradlew ...' }
  },
  devices: {
    simulator: { type: 'ios.simulator', device: { type: 'iPhone 15' } },
    emulator: { type: 'android.emulator', device: { avdName: 'Pixel_4_API_34' } }
  }
};

Comandos de ejecución

Después de la configuración, están disponibles los comandos: detox build — compila la aplicación con banderas de prueba, y detox test — ejecuta las pruebas. Detox soporta la ejecución paralela en múltiples dispositivos mediante la bandera --workers.

Escritura de pruebas con Detox

Las pruebas de Detox se escriben en JavaScript o TypeScript utilizando una API basada en la búsqueda de elementos (matchers) y acciones (actions). Los matchers permiten encontrar un elemento por identificador, texto, tipo o posición en la pantalla. Las acciones realizan toques, entrada de texto, deslizamientos y desplazamiento.

Estructura del escenario de prueba

Una prueba típica sigue esta secuencia: encontrar un elemento → realizar una acción → verificar el resultado. Para las comprobaciones se utiliza la API expect con matchers de presencia, visibilidad o texto del elemento. Detox soporta la sintaxis describe/it mediante la integración con Jest.

describe('Login flow', () => {
  beforeEach(async () => {
    await device.reloadReactNative();
  });

  it('should log in with valid credentials', async () => {
    await element(by.id('emailInput')).typeText('user@test.com');
    await element(by.id('passwordInput')).typeText('password123');
    await element(by.id('loginButton')).tap();
    await expect(element(by.id('homeScreen'))).toBeVisible();
  });
});

Trabajo con gestos

Detox soporta todos los gestos populares: tap, longPress, swipe, scroll, pinch, multiTap. Para scroll se puede especificar la dirección, velocidad y posición de parada. Esto permite probar escenarios complejos como pull-to-refresh o carruseles.

Integración de Detox en CI/CD

Detox se integra bien con sistemas CI populares: GitHub Actions, CircleCI, Bitrise y Jenkins. Para ejecutar en CI, es necesario configurar un simulador iOS virtual (sin GUI) y un emulador Android con aceleración por hardware. Detox proporciona artefactos — capturas de pantalla y registros — para analizar las pruebas fallidas.

Recomendaciones para CI

Para acelerar la ejecución de pruebas en CI, se recomienda usar sharding (paralelización) con la bandera --workers. Detox distribuye automáticamente los archivos de prueba entre múltiples simuladores. También es útil almacenar en caché las compilaciones de la aplicación entre ejecuciones para reducir el tiempo de compilación.

# GitHub Actions — ejecutar Detox en iOS
- name: Install Dependencies
  run: npm ci

- name: Build Detox App
  run: npx detox build --configuration ios.sim

- name: Run Detox Tests
  run: npx detox test --configuration ios.sim --workers 2
  timeout-minutes: 30

Mejores prácticas de Detox

Para pruebas E2E estables y rápidas, se recomienda seguir varias reglas. Evite sleep() — Detox proporciona sincronización automática, y los retrasos explícitos solo ralentizan las pruebas y las hacen inestables. Si una prueba falla debido a problemas de tiempo, primero verifique si la sincronización está deshabilitada. También es útil agrupar las pruebas por funcionalidad y ejecutarlas de forma independiente — esto simplifica la búsqueda de la causa del fallo.

Uso de métodos de device

Detox proporciona varios métodos de device para la gestión del estado: device.reloadReactNative() recarga el bundle, device.launchNewApp() inicia la aplicación con nuevos parámetros, device.sendToHome() minimiza la aplicación. device.setURLBlacklist() permite excluir ciertas URL de la sincronización, lo que es útil para análisis y conexiones long-polling.

Organización de datos de prueba

Para cada prueba, se recomienda crear un estado aislado. Use beforeEach para recargar la aplicación mediante device.reloadReactNative(). Para pruebas que requieren datos específicos, cree fábricas o clientes API para preparar datos en el servidor. Evite dependencias entre pruebas — cada prueba debe ser independiente.

Trabajo con WebView

Detox soporta pruebas de WebView a través de los métodos web.element() y web.invoke(). Para interactuar con elementos web, se utiliza by.web](:id, css o className. Es importante recordar que WebView requiere tiempo adicional de carga — si la sincronización no funciona, añada una espera de carga mediante waitFor.

// Pruebas de WebView en Detox
const webView = web(by.id('webview'));
await webView.element(by.web.cssSelector('#submit-btn')).tap();
const result = await webView.element(
  by.web.cssSelector('.result-text')
).getText();
await expect(result).toEqual('Success');

Pruebas de captura de pantalla

Detox soporta la comparación de capturas de pantalla mediante el plugin detox-image-matching. Las capturas de pantalla permiten detectar regresiones visuales: elementos desplazados, colores incorrectos, iconos faltantes. Para capturas estables, desactive las animaciones y use un tamaño fijo de simulador.

Diagnóstico de problemas de Detox

Los problemas más comunes de Detox están relacionados con la sincronización: animaciones infinitas, solicitudes de red largas o temporizadores bloqueados. El registro con la bandera --loglevel trace muestra qué recursos está esperando Detox. Si Detox se bloquea, use device.disableSynchronization() para el bloque de código problemático.

Problemas con el simulador

En el simulador iOS, Detox requiere que la aplicación se compile primero mediante xcodebuild con la configuración iphonesimulator. Un error común es usar un esquema Release en lugar de Debug, lo que desactiva las banderas de prueba. Para Android, asegúrese de que el AVD se haya creado con una API compatible con su aplicación y que la aceleración Intel HAXM esté habilitada. Para entornos CI en macOS, es conveniente usar GitHub Actions con un runner macOS, donde Xcode y los simuladores ya están preinstalados.

Tiempos de espera de pruebas

Si las pruebas fallan regularmente por tiempo de espera, verifique: si la sincronización está deshabilitada globalmente, si se usan setTimeout o setInterval en el código de la aplicación sin limpieza, y si el hilo principal está bloqueado por una operación larga. A veces ayuda aumentar el tiempo de espera en detoxrc.js mediante testRunner.args.jest.$.testTimeout. Para encontrar áreas problemáticas, active el registro de trazado de Detox — muestra qué recursos y temporizadores está esperando actualmente el framework.

Artefactos e informes

Después de ejecutar las pruebas, Detox crea artefactos: capturas de pantalla de pruebas fallidas, registros de la aplicación e informes XML JUnit. Las capturas de pantalla se toman automáticamente cuando falla una prueba y ayudan a identificar visualmente el problema. Para CI, los artefactos se cargan en el almacenamiento en la nube y están disponibles a través de una interfaz web para analizar las causas del fallo.