Detox: cos’è, principi di funzionamento e test E2E

Cos’è Detox

Detox è un framework per test end-to-end (E2E) di applicazioni mobili, sviluppato da Wix nel 2017. È progettato per progetti React Native ma supporta anche applicazioni puramente native su iOS e Android. Detox funziona con un modello gray-box, il che significa che ha accesso ai meccanismi interni dell’applicazione.

Differenza da altri framework E2E

La principale differenza tra Detox e Appium o Calabash è la sincronizzazione automatica con l’applicazione. Il framework attende il completamento di animazioni, richieste di rete ed elaborazione degli eventi prima di eseguire l’azione successiva. Ciò elimina completamente la necessità di Thread.sleep() o waitForElement, che rallentano i test.

Piattaforme supportate

Detox supporta iOS (tramite XCTest e Xcode) e Android (tramite Espresso e UI Automator). Per le applicazioni React Native, viene fornito il supporto completo per Fabric e la vecchia architettura. Su iOS, i test vengono eseguiti sul simulatore; su Android, sull’emulatore o su un dispositivo reale.

Architettura di Detox e modello gray-box

L’architettura di Detox è composta da tre componenti chiave: Detox CLI, il test runner Detox e Detox Native Driver. Detox CLI gestisce la compilazione, l’installazione e l’esecuzione dei test dell’applicazione. Il test runner (Jest o Mocha) esegue gli scenari di test e comunica con l’applicazione tramite WebSocket.

Approccio gray-box

Il test gray-box significa che Detox ha accesso allo stato interno dell’applicazione attraverso un ponte nativo. Il framework monitora le richieste di rete, le animazioni, i timer e la coda delle operazioni. Quando tutte le code sono vuote, Detox considera l’applicazione pronta per il passo successivo.

Meccanismo di sincronizzazione

La sincronizzazione si basa sul monitoraggio del thread principale dell’applicazione. Detox attende fino al completamento di tutte le animazioni, al ritorno delle risposte delle richieste HTTP e al termine dell’esecuzione dei gestori di eventi. Se un test si blocca a causa di un’animazione infinita, è possibile disabilitare manualmente la sincronizzazione per un blocco di codice specifico.

// Disabilitare la sincronizzazione per una sezione problematica
await device.disableSynchronization();
// Azione con animazione lunga
await element(by.id('loader')).swipe('down');
await device.enableSynchronization();

Installazione e configurazione di Detox

L’installazione di Detox inizia aggiungendo il pacchetto tramite npm o yarn. Dopo l’installazione, è necessario creare un file di configurazione .detoxrc.js, che descrive le impostazioni di compilazione ed esecuzione per ogni piattaforma. Detox utilizza il proprio tipo di compilazione per iOS, basato sulla configurazione di Xcode.

Configurazione di base

La configurazione include il percorso dell’applicazione (app), il tipo di compilatore (build), gli argomenti di compilazione e le impostazioni del dispositivo (device). Per iOS viene utilizzato appleSimulator, per Android androidEmulator. È inoltre possibile specificare gli argomenti di avvio come la lingua o la regione del simulatore.

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

Comandi di avvio

Dopo la configurazione, sono disponibili i seguenti comandi: detox build — compila l’applicazione con i flag di test, e detox test — esegue i test. Detox supporta l’esecuzione parallela su più dispositivi tramite il flag --workers.

Scrivere test con Detox

I test Detox sono scritti in JavaScript o TypeScript utilizzando un’API basata sulla ricerca di elementi (matchers) e azioni (actions). I matchers consentono di trovare un elemento per identificatore, testo, tipo o posizione sullo schermo. Le azioni eseguono tap, inserimento testo, swipe e scroll.

Struttura dello scenario di test

Un test tipico segue questa sequenza: trovare un elemento → eseguire un’azione → verificare il risultato. Per le verifiche, viene utilizzata l’API expect con matchers per presenza, visibilità o testo dell’elemento. Detox supporta la sintassi describe/it tramite l’integrazione 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();
  });
});

Lavorare con i gesti

Detox supporta tutti i gesti popolari: tap, longPress, swipe, scroll, pinch, multiTap. Per scroll è possibile specificare la direzione, la velocità e la posizione di arresto. Ciò consente di testare scenari complessi come pull-to-refresh o caroselli.

Integrazione di Detox in CI/CD

Detox si integra bene con i sistemi CI più diffusi: GitHub Actions, CircleCI, Bitrise e Jenkins. Per l’esecuzione in CI, è necessario configurare un simulatore iOS virtuale (senza interfaccia grafica) e un emulatore Android con accelerazione hardware. Detox fornisce artefatti — screenshot e log — per analizzare i test falliti.

Raccomandazioni per CI

Per accelerare l’esecuzione dei test in CI, si raccomanda di utilizzare lo sharding (parallelizzazione) con il flag --workers. Detox distribuisce automaticamente i file di test tra più simulatori. È anche utile memorizzare nella cache le compilazioni dell’applicazione tra le esecuzioni per ridurre i tempi di compilazione.

# GitHub Actions — eseguire Detox su 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

Migliori pratiche di Detox

Per test E2E stabili e veloci, si raccomanda di seguire diverse regole. Evitate sleep() — Detox fornisce sincronizzazione automatica, e i ritardi espliciti rallentano solo i test e li rendono instabili. Se un test fallisce a causa di problemi di temporizzazione, verificate prima se la sincronizzazione è disabilitata. È anche utile raggruppare i test per funzionalità ed eseguirli indipendentemente — ciò semplifica la ricerca della causa del fallimento.

Utilizzo dei metodi device

Detox fornisce diversi metodi device per la gestione dello stato: device.reloadReactNative() ricarica il bundle, device.launchNewApp() avvia l’applicazione con nuovi parametri, device.sendToHome() minimizza l’applicazione. device.setURLBlacklist() consente di escludere determinati URL dalla sincronizzazione, utile per analisi e connessioni long-polling.

Organizzazione dei dati di test

Per ogni test, si raccomanda di creare uno stato isolato. Utilizzate beforeEach per ricaricare l’applicazione tramite device.reloadReactNative(). Per i test che richiedono dati specifici, create factory o client API per preparare i dati sul server. Evitate dipendenze tra i test — ogni test deve essere indipendente.

Lavorare con WebView

Detox supporta il test di WebView tramite i metodi web.element() e web.invoke(). Per interagire con gli elementi web, viene utilizzato by.web](:id, css o className. È importante ricordare che WebView richiede tempo di caricamento aggiuntivo — se la sincronizzazione non funziona, aggiungete un’attesa di caricamento utilizzando waitFor.

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

Test di screenshot

Detox supporta il confronto di screenshot tramite il plugin detox-image-matching. Gli screenshot consentono di rilevare regressioni visive: elementi spostati, colori errati, icone mancanti. Per screenshot stabili, disattivate le animazioni e utilizzate una dimensione fissa del simulatore.

Diagnostica dei problemi di Detox

I problemi più comuni di Detox sono legati alla sincronizzazione: animazioni infinite, richieste di rete lunghe o timer bloccati. La registrazione con il flag --loglevel trace mostra quali risorse Detox sta attendendo. Se Detox si blocca, utilizzate device.disableSynchronization() per il blocco di codice problematico.

Problemi con il simulatore

Sul simulatore iOS, Detox richiede che l’applicazione venga prima compilata tramite xcodebuild con la configurazione iphonesimulator. Un errore comune è utilizzare uno schema Release invece di Debug, che disabilita i flag di test. Per Android, assicuratevi che l’AVD sia stato creato con un’API compatibile con la vostra applicazione e che l’accelerazione Intel HAXM sia attivata. Per ambienti CI su macOS, è conveniente utilizzare GitHub Actions con un runner macOS, dove Xcode e simulatori sono già preinstallati.

Timeout dei test

Se i test falliscono regolarmente per timeout, verificate: se la sincronizzazione è disabilitata globalmente, se setTimeout o setInterval vengono utilizzati nel codice dell’applicazione senza pulizia, e se il thread principale è bloccato da un’operazione lunga. A volte aiuta aumentare il timeout in detoxrc.js tramite testRunner.args.jest.$.testTimeout. Per trovare le aree problematiche, attivate la registrazione di traccia di Detox — mostra quali risorse e timer il framework sta attualmente attendendo.

Artefatti e report

Dopo l’esecuzione dei test, Detox crea artefatti: screenshot dei test falliti, log dell’applicazione e report XML JUnit. Gli screenshot vengono acquisiti automaticamente quando un test fallisce e aiutano a identificare visivamente il problema. Per CI, gli artefatti vengono caricati nel cloud storage e sono disponibili tramite interfaccia web per analizzare le cause del fallimento.