Detox: какво е, принципи на работа и E2E-тестване

Какво е Detox

Detox е рамка за цялостно (E2E) тестване на мобилни приложения, разработена от компанията Wix през 2017 г. Предназначена е за React Native проекти, но поддържа и чисто native приложения на iOS и Android. Detox работи по gray-box модел, което означава достъп до вътрешните механизми на приложението.

Разлика от други E2E-рамки

Основната разлика на Detox от Appium или Calabash е автоматичната синхронизация с приложението. Рамката изчаква завършването на анимациите, мрежовите заявки и обработката на събития, преди да изпълни следващото действие. Това напълно елиминира необходимостта от Thread.sleep() или waitForElement, които забавят тестовете.

Поддържани платформи

Detox поддържа iOS (чрез XCTest и Xcode) и Android (чрез Espresso и UI Automator). За React Native приложения се осигурява пълна поддръжка за Fabric и старата архитектура. На iOS тестовете се пускат на симулатор, на Android — на емулатор или реално устройство.

Архитектура на Detox и gray-box модел

Архитектурата на Detox се състои от три ключови компонента: Detox CLI, Detox test runner и Detox Native Driver. Detox CLI управлява изграждането на приложението, инсталирането и пускането на тестовете. Test runner-ът (Jest или Mocha) изпълнява тестови сценарии и комуникира с приложението чрез WebSocket.

Gray-box подход

Gray-box тестването означава, че Detox има достъп до вътрешното състояние на приложението чрез native мост. Рамката проследява мрежови заявки, анимации, таймери и опашката от операции. Когато всички опашки са празни — Detox счита приложението за готово за следващата стъпка.

Механизъм на синхронизация

Синхронизацията се основава на проследяване на основната нишка (main thread) на приложението. Detox изчаква докато всички анимации завършат, HTTP заявките върнат отговор и обработчиците на събития се изпълнят. Ако тестът замръзне поради безкрайна анимация — може принудително да се изключи синхронизацията за конкретен блок код.

// Изключване на синхронизацията за проблемния участък
await device.disableSynchronization();
// Действие с дълга анимация
await element(by.id('loader')).swipe('down');
await device.enableSynchronization();

Инсталиране и конфигуриране на Detox

Инсталирането на Detox започва с добавяне на пакета чрез npm или yarn. След инсталиране трябва да се създаде конфигурационен файл .detoxrc.js, в който се описват настройките за изграждане и пускане за всяка платформа. Detox използва собствен тип изграждане за iOS, базиран на Xcode конфигурация.

Основна конфигурация

Конфигурацията включва пътя до приложението (app), типа на строителя (build), аргументите за изграждане и настройките на устройството (device). За iOS се използва appleSimulator, за Android — androidEmulator. Могат също да се зададат аргументи за стартиране, като език или регион на симулатора.

// .detoxrc.js — пример за конфигурация
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' } }
  }
};

Команди за пускане

След конфигуриране са достъпни командите: detox build — изграждане на приложението с тестови флагове и detox test — пускане на тестовете. Detox поддържа паралелно пускане на множество устройства чрез флага --workers.

Писане на тестове с Detox

Тестовете на Detox се пишат на JavaScript или TypeScript, използвайки API, базирано на търсене на елементи (matchers) и действия (actions). Matchers позволяват намиране на елемент по идентификатор, текст, тип или позиция на екрана. Actions изпълняват натискане, въвеждане на текст, плъзгане и превъртане.

Структура на тестов сценарий

Типичен тест изглежда като последователност: намери елемента → изпълни действието → провери резултата. За проверки се използва expect-API с matchers по наличие, видимост или текст на елемента. Detox поддържа describe/it синтаксис чрез интеграция с 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();
  });
});

Работа с жестове

Detox поддържа всички популярни жестове: tap, longPress, swipe, scroll, pinch, multiTap. За scroll може да се зададе посока, скорост и позиция на спиране. Това позволява тестване на сложни сценарии като pull-to-refresh или въртележки.

Интеграция на Detox в CI/CD

Detox се интегрира добре с популярни CI системи: GitHub Actions, CircleCI, Bitrise и Jenkins. За пускане в CI е необходимо конфигуриране на виртуален симулатор iOS (без GUI) и Android емулатор с хардуерно ускорение. Detox предоставя артефакти — екранни снимки и логове — за анализ на неуспешни тестове.

Препоръки за CI

За ускоряване на изпълнението на тестовете в CI се препоръчва използване на sharding (паралелизация) с флага --workers. Detox автоматично разпределя тестовите файлове между няколко симулатора. Също така е полезно кеширането на билдове на приложението между изпълненията за намаляване на времето за изграждане.

# GitHub Actions — пускане на Detox на 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

Най-добри практики за Detox

За стабилни и бързи E2E тестове се препоръчва спазването на няколко правила. Избягвайте sleep() — Detox осигурява автоматична синхронизация, а изричните закъснения само забавят тестовете и ги правят нестабилни. Ако тестът се провали поради времеви проблем, първо проверете дали синхронизацията не е изключена. Също така е полезно групирането на тестовете по функционалности и независимото им пускане — това опростява намирането на причината за провала.

Използване на device методи

Detox предоставя няколко device метода за управление на състоянието: device.reloadReactNative() презарежда bundle, device.launchNewApp() стартира приложението с нови параметри, device.sendToHome() минимизира приложението. device.setURLBlacklist() позволява изключване на определени URL адреси от синхронизация, което е полезно за аналитика и long-polling връзки.

Организация на тестови данни

За всеки тест се препоръчва създаване на изолирано състояние. Използвайте beforeEach за презареждане на приложението чрез device.reloadReactNative(). За тестове, изискващи специфични данни, създавайте фабрики или API клиенти за подготовка на данни на сървъра. Избягвайте зависимости между тестовете — всеки тест трябва да бъде независим.

Работа с WebView

Detox поддържа тестване на WebView чрез методите web.element() и web.invoke(). За взаимодействие с уеб елементи се използва by.web(id, css или className). Важно е да запомните, че WebView изисква допълнително време за зареждане — ако синхронизацията не работи, добавете изчакване на зареждането чрез waitFor.

// Тестване на WebView в 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');

Тестване с екранни снимки

Detox поддържа сравнение на екранни снимки чрез плъгина detox-image-matching. Екранните снимки позволяват откриване на визуални регресии: изместени елементи, грешни цветове, липсващи икони. За стабилни екранни снимки изключете анимациите и използвайте фиксиран размер на симулатора.

Диагностика на проблеми с Detox

Най-честите проблеми с Detox са свързани със синхронизацията: безкрайни анимации, дълги мрежови заявки или замръзнали таймери. Логване с флаг --loglevel trace показва какви ресурси очаква Detox. Ако Detox замръзне — използвайте device.disableSynchronization() за проблемния участък код.

Проблеми със симулатора

На iOS симулатор Detox изисква предварително изграждане на приложението чрез xcodebuild с конфигурация iphonesimulator. Често срещана грешка е използване на Release схема вместо Debug, което изключва тестовите флагове. За Android се уверете, че AVD е създаден с API, съвместим с вашето приложение, и че ускорението Intel HAXM е включено. За CI среди на macOS е удобно да се използва GitHub Actions с macOS runner, където Xcode и симулаторите са вече предварително инсталирани.

Таймаути на тестовете

Ако тестовете редовно се провалят поради таймаут, проверете: дали синхронизацията не е глобално изключена, дали в кода на приложението не се използват setTimeout или setInterval без почистване, и дали основната нишка не е блокирана от продължителна операция. Понякога помага увеличаване на таймаута в detoxrc.js чрез testRunner.args.jest.$.testTimeout. За намиране на проблемни участъци включете проследяващо логване на Detox — то показва какви ресурси и таймери в момента се очакват от рамката.

Артефакти и отчети

След изпълнение на тестовете Detox създава артефакти: екранни снимки на неуспешни тестове, логове на приложението и XML JUnit отчети. Екранните снимки се правят автоматично при провал на тест и помагат визуално да се идентифицира проблемът. За CI артефактите се качват в облачно хранилище и са достъпни чрез уеб интерфейс за анализ на причините за провал.