# wix/detox architecture

> Architecture diagram of the GitHub repository wix/detox, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/wix/detox
- Repository: https://github.com/wix/detox

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User/Test Layer
    subgraph "User/Test Layer"
        direction TB
        TestCode["Test Definitions\n(JavaScript/TypeScript)"]:::external
        TestRunner["Test Runner\n(Jest/Mocha/Cucumber)"]:::external
    end

    %% CLI & Orchestration Layer
    subgraph "CLI & Orchestration Layer"
        direction TB
        DetoxCLI["detox-cli"]:::orchestration
        LocalCLI["Local CLI Commands"]:::orchestration
        ConfigLoader["Configuration Loader"]:::orchestration
        DeviceAllocator["Device Allocator"]:::orchestration
        subgraph "Allocation Drivers"
            direction TB
            EmulatorAllocDriver["Android Emulator/Genymotion\nDriver"]:::orchestration
            SimulatorAllocDriver["iOS Simulator Driver"]:::orchestration
        end
        subgraph "Runtime Drivers"
            direction TB
            AndroidDriver["Android Runtime Driver"]:::orchestration
            SimulatorDriver["iOS Runtime Driver"]:::orchestration
        end
        SessionManager["Test Session Manager"]:::orchestration
        JestAdapter["Jest Adapter"]:::orchestration
        MochaAdapter["Mocha Adapter"]:::orchestration
    end

    %% Core Engine Layer
    subgraph "Core Engine Layer"
        direction TB
        ClientAPI["Detox Client API"]:::core
        AsyncWS["Async WebSocket Transport"]:::core
        IPCClient["IPC Client"]:::core
        IPCServer["IPC Server"]:::core
        SessionState["Session State & Synchronization"]:::core
        SyncFormatter["SyncStatus Formatter"]:::core
    end

    %% Native Automation Layer
    subgraph "Native Automation Layer"
        direction TB
        subgraph Android
            direction TB
            DetoxJava["Detox.java\n(Core Library)"]:::native
            ActionsDispatcher["DetoxActionsDispatcher.kt"]:::native
            EspressoDetox["EspressoDetox.java"]:::native
        end
        subgraph iOS
            direction TB
            DetoxHeader["Detox.h"]:::native
            ActionHandler["ActionHandler.swift"]:::native
        end
    end

    %% Artifact Collection Layer
    subgraph "Artifact Collection Layer"
        direction TB
        ArtifactsManager["Artifacts Manager"]:::orchestration
        ADBLogcatPlugin["ADBLogcat Plugin"]:::orchestration
        ScreenshotPlugin["Screenshot Artifact Plugin"]:::orchestration
        VideoPlugin["Video Artifact Plugin"]:::orchestration
    end

    %% External Integrations
    subgraph "External Integrations"
        direction TB
        CI["CI Pipeline"]:::external
        Website["Documentation Website"]:::external
    end

    %% Data Flows
    TestCode -->|runs via| DetoxCLI
    TestRunner -->|adapter| JestAdapter
    TestRunner -->|adapter| MochaAdapter
    DetoxCLI --> ConfigLoader
    ConfigLoader --> DeviceAllocator
    DeviceAllocator --> EmulatorAllocDriver
    DeviceAllocator --> SimulatorAllocDriver
    EmulatorAllocDriver --> AndroidDriver
    SimulatorAllocDriver --> SimulatorDriver
    AndroidDriver -->|launches| TestRunner
    SimulatorDriver -->|launches| TestRunner
    JestAdapter --> SessionManager
    MochaAdapter --> SessionManager
    SessionManager --> ClientAPI
    ClientAPI --> AsyncWS
    AsyncWS --> IPCClient
    IPCClient -->|WebSocket commands| IPCServer
    IPCServer --> SessionState
    SessionState --> SyncFormatter
    IPCServer -->|dispatch| ActionsDispatcher
    ActionsDispatcher --> DetoxJava
    ActionsDispatcher --> EspressoDetox
    IPCServer -->|dispatch| ActionHandler
    DetoxJava -->|instrumentation| ClientAPI
    EspressoDetox -->|UI actions| ClientAPI
    DetoxHeader -->|instrumentation| ClientAPI
    ActionHandler -->|UI actions| ClientAPI
    ClientAPI -->|captures| ArtifactsManager
    ArtifactsManager --> ADBLogcatPlugin
    ArtifactsManager --> ScreenshotPlugin
    ArtifactsManager --> VideoPlugin
    ArtifactsManager --> CI
    ArtifactsManager --> Website

    %% Click Events
    click DetoxCLI "https://github.com/wix/detox/blob/master/detox-cli/cli.js"
    click LocalCLI "https://github.com/wix/detox/blob/master/detox/local-cli/cli.js"
    click ConfigLoader "https://github.com/wix/detox/blob/master/detox/src/configuration/index.js"
    click DeviceAllocator "https://github.com/wix/detox/blob/master/detox/src/devices/allocation/DeviceAllocator.js"
    click EmulatorAllocDriver "https://github.com/wix/detox/blob/master/detox/src/devices/allocation/drivers/android/emulator/EmulatorAllocDriver.js"
    click SimulatorAllocDriver "https://github.com/wix/detox/blob/master/detox/src/devices/allocation/drivers/ios/SimulatorAllocDriver.js"
    click AndroidDriver "https://github.com/wix/detox/blob/master/detox/src/devices/runtime/drivers/android/AndroidDriver.js"
    click SimulatorDriver "https://github.com/wix/detox/blob/master/detox/src/devices/runtime/drivers/ios/SimulatorDriver.js"
    click JestAdapter "https://github.com/wix/detox/blob/master/detox/runners/jest/adapter.js"
    click MochaAdapter "https://github.com/wix/detox/blob/master/detox/runners/mocha/adapter.js"
    click SessionManager "https://github.com/wix/detox/blob/master/detox/src/server/DetoxSessionManager.js"
    click IPCServer "https://github.com/wix/detox/blob/master/detox/src/ipc/IPCServer.js"
    click IPCClient "https://github.com/wix/detox/blob/master/detox/src/ipc/IPCClient.js"
    click SessionState "https://github.com/wix/detox/blob/master/detox/src/ipc/SessionState.js"
    click ClientAPI "https://github.com/wix/detox/blob/master/detox/src/client/Client.js"
    click AsyncWS "https://github.com/wix/detox/blob/master/detox/src/client/AsyncWebSocket.js"
    click SyncFormatter "https://github.com/wix/detox/blob/master/detox/src/client/actions/formatters/SyncStatusFormatter.js"
    click DetoxJava "https://github.com/wix/detox/blob/master/detox/android/detox/src/full/java/com/wix/detox/Detox.java"
    click ActionsDispatcher "https://github.com/wix/detox/blob/master/detox/android/detox/src/full/java/com/wix/detox/adapters/server/DetoxActionsDispatcher.kt"
    click EspressoDetox "https://github.com/wix/detox/blob/master/detox/android/detox/src/full/java/com/wix/detox/espresso/EspressoDetox.java"
    click DetoxHeader "https://github.com/wix/detox/blob/master/detox/ios/Detox/Detox.h"
    click ActionHandler "https://github.com/wix/detox/blob/master/detox/ios/DetoxXCUITestRunner/DetoxXCUITestRunner/Handlers/ActionHandler.swift"
    click ArtifactsManager "https://github.com/wix/detox/blob/master/detox/src/artifacts/ArtifactsManager.js"
    click ADBLogcatPlugin "https://github.com/wix/detox/blob/master/detox/src/artifacts/log/android/ADBLogcatPlugin.js"
    click ScreenshotPlugin "https://github.com/wix/detox/blob/master/detox/src/artifacts/screenshot/ScreenshotArtifactPlugin.js"
    click VideoPlugin "https://github.com/wix/detox/blob/master/detox/src/artifacts/video/VideoArtifactPlugin.js"
    click CI "https://github.com/wix/detox/blob/master/.buildkite/pipeline.release.yml"
    click Website "https://github.com/wix/detox/blob/master/website/docusaurus.config.js"

    %% Styles
    classDef orchestration fill:#D0E6FF,stroke:#0366d6,color:#0366d6
    classDef core fill:#E0FFE0,stroke:#28A745,color:#28A745
    classDef native fill:#FFE5B4,stroke:#FF8C00,color:#FF8C00
    classDef external fill:#F0F0F0,stroke:#888888,color:#888888
```
