How wix/detox works
Project Type and Purpose
• It provides a CLI, test-runner integrations (Jest, Mocha, Cucumber), a core JavaScript engine, device allocators and drivers, IPC-based communication with instrumented apps, native automation libraries (Espresso on Android, XCUITest on iOS), and artifact collection.
High-Level Architecture Overview
Break the system into these main layers/components:
a. User/Test Layer
• Test Definitions (JavaScript/TypeScript files)
• Test Runner (e.g. Jest, Mocha)
b. CLI & Orchestration Layer
• detox-cli (command line interface)
• Configuration Loader (collects CLI, file, and external configs)
• Device Allocator & Runtime Driver (manages emulators, simulators, real devices)
• Test Session Manager & Runner Adapter (injects hooks into Jest/Mocha)
c. Core Engine Layer
• Client (Node.js module exposing element(), expect(), device API)
• IPC Server (runs in the app under test)
• IPC Client (in the CLI process, talks to IPC Server over WebSocket)
• Session State & Synchronization (SyncStatus, idle detection)
d. Native Automation Layer
• Android: Detox instrumentation library + Espresso adapter
• iOS: Detox dynamic library + XCUITest runner
• Invocation handlers, action dispatchers, matchers, idling resources
e. Artifact Collection Layer
• Artifacts Manager (logs, screenshots, video)
• Plugins (ADB logcat, ADB screencap, Instruments)
f. External Integrations
• CI pipelines (.buildkite, scripts)
• Website and Documentation (static site generator)
Relationships & Data Flows
1. The developer runs detox test via detox-cli.
2. CLI loads configuration, allocates device/emulator, builds and installs the app (native code compiled with Detox libs).
3. CLI launches the test runner (e.g. Jest) with a Detox adapter.
4. Test code calls device.*, element(...), expect(...). Those calls go to the Detox Client module in Node.
5. Detox Client opens a WebSocket/IPC to the Detox Server running inside the app under test.
6. Commands (actions, matchers, idle sync queries) are marshaled over IPC.
7. On Android, the Detox Server hands commands to the Espresso adapter. On iOS, to XCUITest components.
8. The native automation layer performs UI interactions or queries, returns results back over IPC.
9. Detox Client resolves promises in test code.
10. During this process, Artifacts Manager captures logs, screenshots or video frames.
11. On test end or failure, CLI gathers artifacts and emits results via the test-runner reporter.
Key Architectural Patterns & Principles
• Modular layering: clear separation between CLI, core JavaScript, IPC, native libraries, and artifacts.
• Adapter pattern: multiple test runners (Jest, Mocha) and multiple device drivers (Android emulator, Genymotion, iOS simulator).
• Service locator for device selection & allocation.
• Plugin architecture for artifacts and custom drivers.
• IPC-based command dispatch (WebSocket) for real-time communication.
• Automatic synchronization using idling resources and resource monitoring.
Technology & Library Highlights
• Node.js modules: detox-cli, detox core (client, server, configuration, devices), runners (jest-circus, jest, mocha).
• IPC: custom WebSocket implementation over AsyncWebSocket.
• Android native: Java/Kotlin instrumentation library under detox/android/detox/src/full and core.
• iOS native: Objective-C/Swift Detox dynamic library and XCUITest runner under detox/ios.
• Build & CI scripts: bash scripts, Buildkite YAML, Gradle for Android, Xcodebuild for iOS.
Elements
• Clear component names (e.g., “detox-cli”, “DetoxClient”, “DetoxServer”, “EspressoDetox”).
• Notes on configuration flow (where .detoxrc, package.json, environment variables are loaded).
• Artifact flow path to file system or CI logs.