Detox: ce este, principii de funcționare și testare E2E

Ce este Detox

Detox este un framework pentru testarea completă (E2E) a aplicațiilor mobile, dezvoltat de compania Wix în 2017. Este destinat proiectelor React Native, dar suportă și aplicații complet native pe iOS și Android. Detox funcționează după modelul gray-box, ceea ce înseamnă acces la mecanismele interne ale aplicației.

Diferența față de alte frameworkuri E2E

Principala diferență între Detox și Appium sau Calabash este sincronizarea automată cu aplicația. Frameworkul așteaptă finalizarea animațiilor, a cererilor de rețea și a procesării evenimentelor înainte de a executa următoarea acțiune. Aceasta elimină complet necesitatea Thread.sleep() sau waitForElement, care încetinesc testele.

Platforme suportate

Detox suportă iOS (prin XCTest și Xcode) și Android (prin Espresso și UI Automator). Pentru aplicațiile React Native se asigură suport complet pentru Fabric și arhitectura veche. Pe iOS testele se rulează pe simulator, pe Android — pe emulator sau dispozitiv real.

Arhitectura Detox și modelul gray-box

Arhitectura Detox constă din trei componente cheie: Detox CLI, Detox test runner și Detox Native Driver. Detox CLI gestionează construirea aplicației, instalarea și rularea testelor. Test runnerul (Jest sau Mocha) execută scenariile de test și comunică cu aplicația prin WebSocket.

Abordarea gray-box

Testarea gray-box înseamnă că Detox are acces la starea internă a aplicației printr-un pod nativ. Frameworkul monitorizează cererile de rețea, animațiile, temporizatoarele și coada de operații. Când toate cozile sunt goale — Detox consideră aplicația pregătită pentru următorul pas.

Mecanismul de sincronizare

Sincronizarea se bazează pe monitorizarea threadului principal (main thread) al aplicației. Detox așteaptă până când toate animațiile se termină, cererile HTTP returnează răspuns și handler-ele de evenimente se execută. Dacă testul se blochează din cauza unei animații infinite — se poate dezactiva forțat sincronizarea pentru un bloc specific de cod.

// Dezactivarea sincronizării pentru secțiunea problemă
await device.disableSynchronization();
// Acțiune cu animație lungă
await element(by.id('loader')).swipe('down');
await device.enableSynchronization();

Instalarea și configurarea Detox

Instalarea Detox începe cu adăugarea pachetului prin npm sau yarn. După instalare, trebuie creat fișierul de configurare .detoxrc.js, în care se descriu setările de construire și rulare pentru fiecare platformă. Detox folosește propriul tip de build pentru iOS, bazat pe configurarea Xcode.

Configurarea de bază

Configurarea include calea către aplicație (app), tipul builderului (build), argumentele de construire și setările dispozitivului (device). Pentru iOS se folosește appleSimulator, pentru Android — androidEmulator. Se pot specifica și argumente de lansare, precum limba sau regiunea simulatorului.

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

Comenzi de rulare

După configurare sunt disponibile comenzile: detox build — construirea aplicației cu flaguri de testare și detox test — rularea testelor. Detox suportă rularea paralelă pe mai multe dispozitive prin flagul --workers.

Scrierea testelor cu Detox

Testele Detox se scriu în JavaScript sau TypeScript utilizând un API bazat pe căutarea elementelor (matchers) și acțiuni (actions). Matchers permit găsirea unui element după identificator, text, tip sau poziție pe ecran. Actions execută apăsare, introducere text, glisare și derulare.

Structura scenariului de test

Un test tipic arată ca o secvență: găsește elementul → execută acțiunea → verifică rezultatul. Pentru verificări se folosește expect-API cu matchers după prezență, vizibilitate sau textul elementului. Detox suportă sintaxa describe/it prin integrarea cu 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();
  });
});

Lucrul cu gesturi

Detox suportă toate gesturile populare: tap, longPress, swipe, scroll, pinch, multiTap. Pentru scroll se poate specifica direcția, viteza și poziția de oprire. Aceasta permite testarea scenariilor complexe, cum ar fi pull-to-refresh sau carusele.

Integrarea Detox în CI/CD

Detox se integrează bine cu sistemele CI populare: GitHub Actions, CircleCI, Bitrise și Jenkins. Pentru rularea în CI este necesară configurarea unui simulator virtual iOS (fără GUI) și a unui emulator Android cu accelerare hardware. Detox oferă artefacte — capturi de ecran și loguri — pentru analiza testelor eșuate.

Recomandări pentru CI

Pentru accelerarea rulării testelor în CI se recomandă utilizarea shardării (paralelizare) cu flagul --workers. Detox distribuie automat fișierele de test între mai multe simulatoare. De asemenea, este utilă cache-ul buildurilor aplicației între rulări pentru reducerea timpului de construire.

# GitHub Actions — rularea Detox pe 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

Cele mai bune practici Detox

Pentru teste E2E stabile și rapide se recomandă respectarea câtorva reguli. Evitați sleep() — Detox asigură sincronizarea automată, iar întârzierile explicite doar încetinesc testele și le fac instabile. Dacă testul eșuează din cauza timingurilor, verificați mai întâi dacă sincronizarea nu este dezactivată. De asemenea, gruparea testelor pe funcționalități și rularea lor independentă simplifică găsirea cauzei eșecului.

Utilizarea metodelor device

Detox oferă mai multe metode device pentru gestionarea stării: device.reloadReactNative() reîncarcă bundle-ul, device.launchNewApp() lansează aplicația cu parametri noi, device.sendToHome() minimizează aplicația. device.setURLBlacklist() permite excluderea anumitor URL-uri din sincronizare, util pentru analitică și conexiuni long-polling.

Organizarea datelor de test

Pentru fiecare test se recomandă crearea unei stări izolate. Utilizați beforeEach pentru reîncărcarea aplicației prin device.reloadReactNative(). Pentru testele care necesită date specifice, creați fabrici sau clienți API pentru pregătirea datelor pe server. Evitați dependențele între teste — fiecare test trebuie să fie independent.

Lucrul cu WebView

Detox suportă testarea WebView prin metodele web.element() și web.invoke(). Pentru interacțiunea cu elementele web se folosește by.web(id, css sau className). Este important de reținut că WebView necesită timp suplimentar de încărcare — dacă sincronizarea nu funcționează, adăugați așteptarea încărcării prin waitFor.

// Testarea WebView în 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');

Testarea prin capturi de ecran

Detox suportă compararea capturilor de ecran prin pluginul detox-image-matching. Capturile de ecran permit detectarea regresiilor vizuale: elemente deplasate, culori incorecte, pictograme lipsă. Pentru capturi stabile, dezactivați animațiile și utilizați o dimensiune fixă a simulatorului.

Diagnosticarea problemelor Detox

Cele mai frecvente probleme Detox sunt legate de sincronizare: animații infinite, cereri de rețea lungi sau timeruri blocate. Logarea cu flagul --loglevel trace arată ce resurse așteaptă Detox. Dacă Detox se blochează — utilizați device.disableSynchronization() pentru secțiunea problemă de cod.

Probleme cu simulatorul

Pe simulatorul iOS, Detox necesită construirea prealabilă a aplicației prin xcodebuild cu configurarea iphonesimulator. O eroare frecventă este utilizarea schemei Release în loc de Debug, care dezactivează flagurile de testare. Pentru Android, asigurați-vă că AVD este creat cu API compatibil cu aplicația dvs. și că accelerarea Intel HAXM este activată. Pentru medii CI pe macOS, este convenabil să utilizați GitHub Actions cu un runner macOS, unde Xcode și simulatoarele sunt deja preinstalate.

Timeouturile testelor

Dacă testele eșuează regulat din cauza timeoutului, verificați: dacă sincronizarea nu este dezactivată global, dacă în codul aplicației nu sunt utilizate setTimeout sau setInterval fără curățare și dacă threadul principal nu este blocat de o operație lungă. Uneori ajută creșterea timeoutului în detoxrc.js prin testRunner.args.jest.$.testTimeout. Pentru găsirea secțiunilor problematice, activați logarea de urmărire Detox — aceasta arată ce resurse și timeruri sunt așteptate în prezent de framework.

Artefacte și rapoarte

După rularea testelor, Detox creează artefacte: capturi de ecran ale testelor eșuate, loguri ale aplicației și rapoarte XML JUnit. Capturile de ecran se fac automat la eșecul testului și ajută la identificarea vizuală a problemei. Pentru CI, artefactele sunt încărcate în stocare în cloud și accesibile prin interfața web pentru analiza cauzelor eșecului.