Detox: Was es ist, Funktionsprinzipien und E2E-Tests

Was ist Detox

Detox ist ein Framework für End-to-End (E2E)-Tests mobiler Anwendungen, das 2017 von Wix entwickelt wurde. Es ist für React Native-Projekte konzipiert, unterstützt aber auch rein native Anwendungen auf iOS und Android. Detox arbeitet nach dem Gray-Box-Modell, was bedeutet, dass es Zugriff auf die internen Mechanismen der Anwendung hat.

Unterschied zu anderen E2E-Frameworks

Der Hauptunterschied zwischen Detox und Appium oder Calabash ist die automatische Synchronisierung mit der Anwendung. Das Framework wartet auf den Abschluss von Animationen, Netzwerkanfragen und Ereignisverarbeitung, bevor es die nächste Aktion ausführt. Dadurch wird die Notwendigkeit von Thread.sleep() oder waitForElement, die Tests verlangsamen, vollständig eliminiert.

Unterstützte Plattformen

Detox unterstützt iOS (über XCTest und Xcode) und Android (über Espresso und UI Automator). Für React Native-Anwendungen wird volle Unterstützung für Fabric und die alte Architektur bereitgestellt. Auf iOS laufen Tests auf dem Simulator, auf Android auf dem Emulator oder einem echten Gerät.

Detox-Architektur und Gray-Box-Modell

Die Detox-Architektur besteht aus drei Schlüsselkomponenten: Detox CLI, Detox-Testrunner und Detox Native Driver. Detox CLI verwaltet den Build, die Installation und die Testausführung der Anwendung. Der Testrunner (Jest oder Mocha) führt Testszenarien aus und kommuniziert über WebSocket mit der Anwendung.

Gray-Box-Ansatz

Gray-Box-Tests bedeuten, dass Detox über eine native Brücke Zugriff auf den internen Zustand der Anwendung hat. Das Framework überwacht Netzwerkanfragen, Animationen, Timer und die Operationswarteschlange. Wenn alle Warteschlangen leer sind, betrachtet Detox die Anwendung als bereit für den nächsten Schritt.

Synchronisierungsmechanismus

Die Synchronisierung basiert auf der Überwachung des Hauptthreads der Anwendung. Detox wartet, bis alle Animationen abgeschlossen sind, HTTP-Anfragen Antworten zurückgeben und Ereignisbehandler die Ausführung beendet haben. Wenn ein Test aufgrund einer unendlichen Animation hängt, kann die Synchronisierung für einen bestimmten Codeblock manuell deaktiviert werden.

// Deaktivieren der Synchronisierung für einen problematischen Abschnitt
await device.disableSynchronization();
// Aktion mit langer Animation
await element(by.id('loader')).swipe('down');
await device.enableSynchronization();

Installation und Konfiguration von Detox

Die Installation von Detox beginnt mit dem Hinzufügen des Pakets über npm oder yarn. Nach der Installation muss eine Konfigurationsdatei .detoxrc.js erstellt werden, die die Build- und Ausführungseinstellungen für jede Plattform beschreibt. Detox verwendet für iOS einen eigenen Build-Typ, der auf der Xcode-Konfiguration basiert.

Basiskonfiguration

Die Konfiguration umfasst den Pfad zur Anwendung (app), den Buildertyp (build), Build-Argumente und Geräteeinstellungen (device). Für iOS wird appleSimulator verwendet, für Android androidEmulator. Sie können auch Startargumente wie die Sprache oder Region des Simulators angeben.

// .detoxrc.js — Konfigurationsbeispiel
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' } }
  }
};

Startbefehle

Nach der Konfiguration stehen folgende Befehle zur Verfügung: detox build — erstellt die Anwendung mit Testflags, und detox test — führt die Tests aus. Detox unterstützt die parallele Ausführung auf mehreren Geräten mit dem Flag --workers.

Tests mit Detox schreiben

Detox-Tests werden in JavaScript oder TypeScript mit einer API geschrieben, die auf Elementsuche (Matcher) und Aktionen (Actions) basiert. Matcher ermöglichen es, ein Element nach Identifikator, Text, Typ oder Position auf dem Bildschirm zu finden. Aktionen führen Tippen, Texteingabe, Wischen und Scrollen aus.

Struktur eines Testszenarios

Ein typischer Test folgt dieser Reihenfolge: Element finden → Aktion ausführen → Ergebnis überprüfen. Für Überprüfungen wird die expect-API mit Matchern für Vorhandensein, Sichtbarkeit oder Text des Elements verwendet. Detox unterstützt die describe/it-Syntax durch Integration mit 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();
  });
});

Arbeiten mit Gesten

Detox unterstützt alle gängigen Gesten: Tap, LongPress, Swipe, Scroll, Pinch, MultiTap. Für Scroll können Sie Richtung, Geschwindigkeit und Stopposition angeben. Dies ermöglicht das Testen komplexer Szenarien wie Pull-to-Refresh oder Karussells.

Integration von Detox in CI/CD

Detox lässt sich gut in gängige CI-Systeme integrieren: GitHub Actions, CircleCI, Bitrise und Jenkins. Für die Ausführung in CI müssen ein virtueller iOS-Simulator (ohne GUI) und ein Android-Emulator mit Hardwarebeschleunigung eingerichtet werden. Detox stellt Artefakte — Screenshots und Logs — zur Analyse fehlgeschlagener Tests bereit.

Empfehlungen für CI

Um die Testausführung in CI zu beschleunigen, wird die Verwendung von Sharding (Parallelisierung) mit dem Flag --workers empfohlen. Detox verteilt Testdateien automatisch auf mehrere Simulatoren. Es ist auch nützlich, Anwendungs-Builds zwischen den Ausführungen zwischenzuspeichern, um die Build-Zeit zu reduzieren.

# GitHub Actions — Detox auf iOS ausführen
- 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

Detox Best Practices

Für stabile und schnelle E2E-Tests wird empfohlen, mehrere Regeln zu befolgen. Vermeiden Sie sleep() — Detox bietet automatische Synchronisierung, und explizite Verzögerungen verlangsamen Tests nur und machen sie instabil. Wenn ein Test aufgrund von Zeitproblemen fehlschlägt, überprüfen Sie zunächst, ob die Synchronisierung deaktiviert ist. Es ist auch nützlich, Tests nach Funktionen zu gruppieren und unabhängig auszuführen — dies vereinfacht die Suche nach der Fehlerursache.

Verwendung von Device-Methoden

Detox bietet mehrere Device-Methoden zur Zustandsverwaltung: device.reloadReactNative() lädt das Bundle neu, device.launchNewApp() startet die Anwendung mit neuen Parametern, device.sendToHome() minimiert die Anwendung. device.setURLBlacklist() ermöglicht es, bestimmte URLs von der Synchronisierung auszuschließen, was für Analysen und Long-Polling-Verbindungen nützlich ist.

Organisation von Testdaten

Für jeden Test wird empfohlen, einen isolierten Zustand zu erstellen. Verwenden Sie beforeEach, um die Anwendung über device.reloadReactNative() neu zu laden. Erstellen Sie für Tests, die spezifische Daten erfordern, Fabriken oder API-Clients, um Daten auf dem Server vorzubereiten. Vermeiden Sie Abhängigkeiten zwischen Tests — jeder Test sollte unabhängig sein.

Arbeiten mit WebView

Detox unterstützt das Testen von WebView über die Methoden web.element() und web.invoke(). Zur Interaktion mit Web-Elementen wird by.web](:id, css oder className verwendet. Es ist wichtig zu bedenken, dass WebView zusätzliche Ladezeit benötigt — wenn die Synchronisierung nicht funktioniert, fügen Sie eine Lade-Wartezeit mit waitFor hinzu.

// WebView-Tests in 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');

Screenshot-Tests

Detox unterstützt den Vergleich von Screenshots über das Plugin detox-image-matching. Screenshots ermöglichen die Erkennung visueller Regressionen: verschobene Elemente, falsche Farben, fehlende Symbole. Für stabile Screenshots deaktivieren Sie Animationen und verwenden Sie eine feste Simulatorgröße.

Diagnose von Detox-Problemen

Die häufigsten Detox-Probleme hängen mit der Synchronisierung zusammen: unendliche Animationen, lange Netzwerkanfragen oder hängende Timer. Die Protokollierung mit dem Flag --loglevel trace zeigt, welche Ressourcen Detox erwartet. Wenn Detox hängt, verwenden Sie device.disableSynchronization() für den problematischen Codeblock.

Probleme mit dem Simulator

Auf dem iOS-Simulator erfordert Detox, dass die Anwendung zunächst über xcodebuild mit der Konfiguration iphonesimulator erstellt wird. Ein häufiger Fehler ist die Verwendung des Release-Schemas anstelle von Debug, wodurch Testflags deaktiviert werden. Stellen Sie bei Android sicher, dass das AVD mit einer mit Ihrer Anwendung kompatiblen API erstellt wurde und die Intel HAXM-Beschleunigung aktiviert ist. Für CI-Umgebungen unter macOS ist es praktisch, GitHub Actions mit einem macOS-Runner zu verwenden, wo Xcode und Simulatoren bereits vorinstalliert sind.

Test-Timeout

Wenn Tests regelmäßig aufgrund von Timeout fehlschlagen, überprüfen Sie: ob die Synchronisierung global deaktiviert ist, ob setTimeout oder setInterval im Anwendungscode ohne Bereinigung verwendet werden und ob der Hauptthread durch einen langen Vorgang blockiert wird. Manchmal hilft es, das Timeout in detoxrc.js über testRunner.args.jest.$.testTimeout zu erhöhen. Um Problembereiche zu finden, aktivieren Sie die Trace-Protokollierung von Detox — sie zeigt, welche Ressourcen und Timer das Framework derzeit erwartet.

Artefakte und Berichte

Nach der Testausführung erstellt Detox Artefakte: Screenshots fehlgeschlagener Tests, Anwendungslogs und JUnit-XML-Berichte. Screenshots werden automatisch bei Testfehlern erstellt und helfen, das Problem visuell zu identifizieren. Für CI werden Artefakte in die Cloud hochgeladen und sind über eine Weboberfläche zur Analyse der Fehlerursachen verfügbar.