Detox: co to, zasady działania i E2E-testowanie

Czym jest Detox

Detox to framework do kompleksowego (E2E) testowania aplikacji mobilnych, opracowany przez firmę Wix w 2017 roku. Jest przeznaczony dla projektów React Native, ale obsługuje również czysto natywne aplikacje na iOS i Android. Detox działa w modelu gray-box, co oznacza dostęp do wewnętrznych mechanizmów aplikacji.

Różnica w stosunku do innych frameworków E2E

Główna różnica między Detox a Appium czy Calabash to automatyczna synchronizacja z aplikacją. Framework oczekuje na zakończenie animacji, zapytań sieciowych i przetwarzania zdarzeń przed wykonaniem kolejnej akcji. Całkowicie eliminuje to potrzebę stosowania Thread.sleep() lub waitForElement, które spowalniają testy.

Obsługiwane platformy

Detox obsługuje iOS (przez XCTest i Xcode) oraz Android (przez Espresso i UI Automator). Dla aplikacji React Native zapewnia pełne wsparcie dla Fabric i starej architektury. Na iOS testy uruchamiane są na symulatorze, na Android — na emulatorze lub rzeczywistym urządzeniu.

Architektura Detox i model gray-box

Architektura Detox składa się z trzech kluczowych komponentów: Detox CLI, Detox test runnera i Detox Native Driver. Detox CLI zarządza budowaniem aplikacji, instalacją i uruchamianiem testów. Test runner (Jest lub Mocha) wykonuje scenariusze testowe i komunikuje się z aplikacją przez WebSocket.

Podejście gray-box

Testowanie gray-box oznacza, że Detox ma dostęp do wewnętrznego stanu aplikacji przez natywny most. Framework śledzi zapytania sieciowe, animacje, timery i kolejkę operacji. Gdy wszystkie kolejki są puste — Detox uznaje aplikację za gotową do następnego kroku.

Mechanizm synchronizacji

Synchronizacja opiera się na śledzeniu głównego wątku (main thread) aplikacji. Detox czeka, aż wszystkie animacje się zakończą, zapytania HTTP zwrócą odpowiedź i procedury obsługi zdarzeń zostaną wykonane. Jeśli test zawiesza się z powodu nieskończonej animacji — można wymusić wyłączenie synchronizacji dla konkretnego bloku kodu.

// Wyłączenie synchronizacji dla problematycznego fragmentu
await device.disableSynchronization();
// Akcja z długotrwałą animacją
await element(by.id('loader')).swipe('down');
await device.enableSynchronization();

Instalacja i konfiguracja Detox

Instalacja Detox rozpoczyna się od dodania pakietu przez npm lub yarn. Po instalacji należy utworzyć plik konfiguracyjny .detoxrc.js, w którym opisane są ustawienia budowania i uruchamiania dla każdej platformy. Detox używa własnego typu budowania dla iOS, opartego na konfiguracji Xcode.

Podstawowa konfiguracja

Konfiguracja obejmuje ścieżkę do aplikacji (app), typ buildera (build), argumenty budowania i ustawienia urządzenia (device). Dla iOS używany jest appleSimulator, dla Android — androidEmulator. Można również określić argumenty uruchamiania, takie jak język czy region symulatora.

// .detoxrc.js — przykład konfiguracji
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' } }
  }
};

Polecenia uruchamiania

Po konfiguracji dostępne są polecenia: detox build — budowanie aplikacji z flagami testowymi, oraz detox test — uruchamianie testów. Detox obsługuje równoległe uruchamianie na wielu urządzeniach przez flagę --workers.

Pisanie testów w Detox

Testy Detox pisane są w JavaScript lub TypeScript z użyciem API opartego na wyszukiwaniu elementów (matchers) i akcjach (actions). Matchers pozwalają znaleźć element po identyfikatorze, tekście, typie lub pozycji na ekranie. Actions wykonują kliknięcie, wprowadzanie tekstu, przesunięcie i przewijanie.

Struktura scenariusza testowego

Typowy test wygląda jako sekwencja: znajdź element → wykonaj akcję → sprawdź wynik. Do sprawdzania używane jest expect-API z matchers według obecności, widoczności lub tekstu elementu. Detox obsługuje składnię describe/it poprzez integrację z 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();
  });
});

Praca z gestami

Detox obsługuje wszystkie popularne gesty: tap, longPress, swipe, scroll, pinch, multiTap. Dla scroll można określić kierunek, prędkość i pozycję zatrzymania. Pozwala to testować złożone scenariusze, takie jak pull-to-refresh czy karuzele.

Integracja Detox z CI/CD

Detox dobrze integruje się z popularnymi systemami CI: GitHub Actions, CircleCI, Bitrise i Jenkins. Do uruchomienia w CI wymagane jest skonfigurowanie wirtualnego symulatora iOS (bez GUI) i emulatora Android z akceleracją sprzętową. Detox dostarcza artefakty — zrzuty ekranu i logi — do analizy nieudanych testów.

Zalecenia dla CI

W celu przyspieszenia przebiegu testów w CI zaleca się stosowanie shardowania (parallelization) z flagą --workers. Detox automatycznie rozdziela pliki testowe między wiele symulatorów. Przydatne jest również cachowanie buildów aplikacji między uruchomieniami w celu skrócenia czasu budowania.

# GitHub Actions — uruchamianie Detox na 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

Najlepsze praktyki Detox

Dla stabilnych i szybkich testów E2E zaleca się przestrzeganie kilku zasad. Unikaj sleep() — Detox zapewnia automatyczną synchronizację, a jawne opóźnienia tylko spowalniają testy i czynią je niestabilnymi. Jeśli test pada z powodu timingów, najpierw sprawdź, czy synchronizacja nie jest wyłączona. Przydatne jest również grupowanie testów według funkcji i uruchamianie ich niezależnie — upraszcza to szukanie przyczyny błędu.

Korzystanie z metod device

Detox udostępnia kilka metod device do zarządzania stanem: device.reloadReactNative() przeładowuje bundle, device.launchNewApp() uruchamia aplikację z nowymi parametrami, device.sendToHome() minimalizuje aplikację. device.setURLBlacklist() pozwala wykluczyć określone URL-e z synchronizacji, co jest przydatne dla analityki i połączeń long-polling.

Organizacja danych testowych

Dla każdego testu zaleca się tworzenie izolowanego stanu. Używaj beforeEach do przeładowania aplikacji przez device.reloadReactNative(). Dla testów wymagających specyficznych danych twórz fabryki lub klientów API do przygotowania danych na serwerze. Unikaj zależności między testami — każdy test powinien być niezależny.

Praca z WebView

Detox obsługuje testowanie WebView przez metody web.element() i web.invoke(). Do interakcji z elementami webowymi używane jest by.web(id, css lub className). Ważne jest, że WebView wymaga dodatkowego czasu na ładowanie — jeśli synchronizacja nie działa, dodaj oczekiwanie na załadowanie przez waitFor.

// Testowanie WebView w 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');

Testy zrzutów ekranu

Detox obsługuje porównywanie zrzutów ekranu przez plugin detox-image-matching. Zrzuty ekranu pozwalają wykryć regresje wizualne: przesunięte elementy, nieprawidłowe kolory, brakujące ikony. Dla stabilnych zrzutów wyłączaj animacje i używaj stałego rozmiaru symulatora.

Diagnostyka problemów Detox

Najczęstsze problemy Detox związane są z synchronizacją: nieskończone animacje, długie zapytania sieciowe lub zawieszone timery. Logowanie z flagą --loglevel trace pokazuje, jakie zasoby oczekuje Detox. Jeśli Detox się zawiesza — użyj device.disableSynchronization() dla problematycznego fragmentu kodu.

Problemy z symulatorem

Na symulatorze iOS Detox wymaga wcześniejszego budowania aplikacji przez xcodebuild z konfiguracją iphonesimulator. Częsty błąd to użycie schematu Release zamiast Debug, co wyłącza flagi testowania. Dla Android upewnij się, że AVD został utworzony z API kompatybilnym z twoją aplikacją i że akceleracja Intel HAXM jest włączona. Dla środowisk CI na macOS wygodnie jest używać GitHub Actions z runnerem macOS, gdzie Xcode i symulatory są już preinstalowane.

Timeouty testów

Jeśli testy regularnie padają z powodu timeoutu, sprawdź: czy synchronizacja nie jest wyłączona globalnie, czy w kodzie aplikacji nie są używane setTimeout lub setInterval bez czyszczenia, oraz czy główny wątek nie jest blokowany przez długotrwałą operację. Czasami pomaga zwiększenie timeoutu w detoxrc.js przez testRunner.args.jest.$.testTimeout. Do szukania problematycznych fragmentów włącz logowanie śledzące Detox — pokazuje ono, jakie zasoby i timery są obecnie oczekiwane przez framework.

Artefakty i raporty

Po przebiegu testów Detox tworzy artefakty: zrzuty ekranu nieudanych testów, logi aplikacji i raporty XML JUnit. Zrzuty ekranu są wykonywane automatycznie przy nieudanym teście i pomagają wizualnie zidentyfikować problem. Dla CI artefakty są przesyłane do magazynu w chmurze i dostępne przez interfejs webowy do analizy przyczyn błędów.