Detox : ce que c’est, principes de fonctionnement et tests E2E

Qu’est-ce que Detox

Detox est un framework de tests de bout en bout (E2E) pour applications mobiles, développé par Wix en 2017. Il est conçu pour les projets React Native mais prend également en charge les applications purement natives sur iOS et Android. Detox fonctionne selon un modèle gray-box, ce qui signifie qu’il a accès aux mécanismes internes de l’application.

Différence avec les autres frameworks E2E

La principale différence entre Detox et Appium ou Calabash est la synchronisation automatique avec l’application. Le framework attend la fin des animations, des requêtes réseau et du traitement des événements avant d’exécuter l’action suivante. Cela élimine complètement le besoin de Thread.sleep() ou waitForElement, qui ralentissent les tests.

Plateformes prises en charge

Detox prend en charge iOS (via XCTest et Xcode) et Android (via Espresso et UI Automator). Pour les applications React Native, une prise en charge complète est fournie pour Fabric et l’ancienne architecture. Sur iOS, les tests s’exécutent sur le simulateur ; sur Android, sur l’émulateur ou un appareil réel.

Architecture de Detox et modèle gray-box

L’architecture de Detox se compose de trois composants clés : Detox CLI, l’exécuteur de tests Detox et Detox Native Driver. Detox CLI gère la compilation, l’installation et l’exécution des tests de l’application. L’exécuteur de tests (Jest ou Mocha) exécute les scénarios de test et communique avec l’application via WebSocket.

Approche gray-box

Les tests gray-box signifient que Detox a accès à l’état interne de l’application via un pont natif. Le framework surveille les requêtes réseau, les animations, les temporisateurs et la file d’opérations. Lorsque toutes les files sont vides, Detox considère l’application prête pour l’étape suivante.

Mécanisme de synchronisation

La synchronisation est basée sur la surveillance du thread principal de l’application. Detox attend que toutes les animations soient terminées, que les requêtes HTTP aient renvoyé des réponses et que les gestionnaires d’événements aient fini de s’exécuter. Si un test se bloque à cause d’une animation infinie, vous pouvez désactiver manuellement la synchronisation pour un bloc de code spécifique.

// Désactiver la synchronisation pour une section problématique
await device.disableSynchronization();
// Action avec animation longue
await element(by.id('loader')).swipe('down');
await device.enableSynchronization();

Installation et configuration de Detox

L’installation de Detox commence par l’ajout du package via npm ou yarn. Après l’installation, vous devez créer un fichier de configuration .detoxrc.js, qui décrit les paramètres de compilation et d’exécution pour chaque plateforme. Detox utilise son propre type de compilation pour iOS, basé sur la configuration Xcode.

Configuration de base

La configuration inclut le chemin vers l’application (app), le type de compilateur (build), les arguments de compilation et les paramètres de l’appareil (device). Pour iOS, appleSimulator est utilisé ; pour Android, androidEmulator. Vous pouvez également spécifier des arguments de lancement comme la langue ou la région du simulateur.

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

Commandes de lancement

Après la configuration, les commandes suivantes sont disponibles : detox build — compile l’application avec les flags de test, et detox test — exécute les tests. Detox prend en charge l’exécution parallèle sur plusieurs appareils via le flag --workers.

Rédaction de tests avec Detox

Les tests Detox sont écrits en JavaScript ou TypeScript avec une API basée sur la recherche d’éléments (matchers) et les actions (actions). Les matchers permettent de trouver un élément par identifiant, texte, type ou position sur l’écran. Les actions effectuent des tap, saisie de texte, swipe et scroll.

Structure d’un scénario de test

Un test typique suit cette séquence : trouver un élément → effectuer une action → vérifier le résultat. Pour les vérifications, l’API expect est utilisée avec des matchers de présence, visibilité ou texte de l’élément. Detox prend en charge la syntaxe describe/it via l’intégration avec 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();
  });
});

Travailler avec les gestes

Detox prend en charge tous les gestes populaires : tap, longPress, swipe, scroll, pinch, multiTap. Pour scroll, vous pouvez spécifier la direction, la vitesse et la position d’arrêt. Cela permet de tester des scénarios complexes comme le pull-to-refresh ou les carrousels.

Intégration de Detox dans CI/CD

Detox s’intègre bien avec les systèmes CI populaires : GitHub Actions, CircleCI, Bitrise et Jenkins. Pour l’exécution dans CI, vous devez configurer un simulateur iOS virtuel (sans interface graphique) et un émulateur Android avec accélération matérielle. Detox fournit des artefacts — captures d’écran et journaux — pour analyser les tests échoués.

Recommandations pour CI

Pour accélérer l’exécution des tests dans CI, il est recommandé d’utiliser le sharding (parallélisation) avec le flag --workers. Detox distribue automatiquement les fichiers de test entre plusieurs simulateurs. Il est également utile de mettre en cache les compilations de l’application entre les exécutions pour réduire le temps de compilation.

# GitHub Actions — exécuter Detox sur 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

Meilleures pratiques Detox

Pour des tests E2E stables et rapides, il est recommandé de suivre plusieurs règles. Évitez sleep() — Detox fournit une synchronisation automatique, et les délais explicites ne font que ralentir les tests et les rendre instables. Si un test échoue en raison de problèmes de temporisation, vérifiez d’abord si la synchronisation est désactivée. Il est également utile de regrouper les tests par fonctionnalité et de les exécuter indépendamment — cela simplifie la recherche de la cause de l’échec.

Utilisation des méthodes device

Detox fournit plusieurs méthodes device pour la gestion d’état : device.reloadReactNative() recharge le bundle, device.launchNewApp() lance l’application avec de nouveaux paramètres, device.sendToHome() minimise l’application. device.setURLBlacklist() permet d’exclure certaines URL de la synchronisation, ce qui est utile pour les analyses et les connexions long-polling.

Organisation des données de test

Pour chaque test, il est recommandé de créer un état isolé. Utilisez beforeEach pour recharger l’application via device.reloadReactNative(). Pour les tests nécessitant des données spécifiques, créez des fabriques ou des clients API pour préparer les données sur le serveur. Évitez les dépendances entre les tests — chaque test doit être indépendant.

Travailler avec WebView

Detox prend en charge les tests WebView via les méthodes web.element() et web.invoke(). Pour interagir avec les éléments web, by.web](:id, css ou className est utilisé. Il est important de se rappeler que WebView nécessite un temps de chargement supplémentaire — si la synchronisation ne fonctionne pas, ajoutez une attente de chargement avec waitFor.

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

Tests de capture d’écran

Detox prend en charge la comparaison de captures d’écran via le plugin detox-image-matching. Les captures d’écran permettent de détecter les régressions visuelles : éléments déplacés, couleurs incorrectes, icônes manquantes. Pour des captures stables, désactivez les animations et utilisez une taille de simulateur fixe.

Diagnostic des problèmes Detox

Les problèmes les plus courants de Detox sont liés à la synchronisation : animations infinies, longues requêtes réseau ou temporisateurs bloqués. La journalisation avec le flag --loglevel trace montre les ressources que Detox attend. Si Detox se bloque, utilisez device.disableSynchronization() pour le bloc de code problématique.

Problèmes de simulateur

Sur le simulateur iOS, Detox nécessite que l’application soit d’abord compilée via xcodebuild avec la configuration iphonesimulator. Une erreur courante est d’utiliser un schéma Release au lieu de Debug, ce qui désactive les flags de test. Pour Android, assurez-vous que l’AVD a été créé avec une API compatible avec votre application et que l’accélération Intel HAXM est activée. Pour les environnements CI sur macOS, il est pratique d’utiliser GitHub Actions avec un runner macOS, où Xcode et les simulateurs sont déjà préinstallés.

Délais d’attente des tests

Si les tests échouent régulièrement en raison d’un délai d’attente, vérifiez : si la synchronisation est désactivée globalement, si setTimeout ou setInterval sont utilisés dans le code de l’application sans nettoyage, et si le thread principal est bloqué par une opération longue. Parfois, l’augmentation du délai d’attente dans detoxrc.js via testRunner.args.jest.$.testTimeout aide. Pour trouver les zones à problème, activez la journalisation de trace de Detox — elle montre les ressources et temporisateurs que le framework attend actuellement.

Artefacts et rapports

Après l’exécution des tests, Detox crée des artefacts : captures d’écran des tests échoués, journaux d’application et rapports XML JUnit. Les captures d’écran sont prises automatiquement en cas d’échec d’un test et aident à identifier visuellement le problème. Pour CI, les artefacts sont téléchargés dans le stockage cloud et disponibles via une interface web pour analyser les causes de l’échec.