# qawolf/webdriveragent architecture

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

- Interactive diagram: https://gitdiagram.com/qawolf/webdriveragent
- Repository: https://github.com/qawolf/webdriveragent

## Overview

##### Project Type and Purpose
- This is an open-source tool (a Node.js package with native iOS/tvOS components) implementing a WebDriver server on Apple devices.
- Purpose: compile and install a WebDriverAgent (WDA) XCUITest bundle on a device or simulator, launch it, expose a HTTP/WebDriver API for remote control, and proxy those calls back to the Appium client.

##### High-Level Components
A. Host (macOS) / Node.js Side
1. CLI / Entry Point (index.ts)
2. Build & Deployment Layer
- Scripts (Scripts/*, lib/xcodebuild.js) invoke `xcodebuild`, manage simulator vs. real device, fetch or bundle WDA.
3. Proxy & Session Management
- lib/webdriveragent.js
- lib/no-session-proxy.js
- lib/utils.js, constants, logger
4. HTTP Proxy Server
- Exposes a local HTTP/WebDriver-compatible endpoint to Appium.
- Receives client (Appium) WebDriver commands; forwards them to the WDA server over a tunnel.
B. Device / Simulator Side
1. XCTest Runner (WebDriverAgentRunner)
- Xcode test target that is signed and deployed.
2. HTTP Server & Routing
- CocoaHTTPServer + RoutingHTTPServer (integrated in WebDriverAgentLib/Vendor)
- FBWebServer, FBRoute, FBCommandHandler, FBResponseJSONPayload, etc.
3. Command Modules
- Commands under WebDriverAgentLib/Commands (FBElementCommands, FBScreenshotCommands, etc.)
4. Utilities & Categories
- Accessibility and UI interaction helpers (WebDriverAgentLib/Utilities & Categories)
- Element caching, screenshot, screen recording, W3C actions, etc.
5. XCTest & Accessibility Frameworks
- Linked system frameworks (`XCTest.framework`, `XCUITest`, `UIKitCore`, `AccessibilityUtilities`, etc.)

##### Relationships and Data Flow
1. Appium Client → HTTP Proxy (Node.js)
- Outgoing WebDriver JSON commands
2. HTTP Proxy → Tunnel / USBMux (node uses xcodebuild flags to forward a TCP port)
3. Tunnel → WDA HTTP Server on Device
- RoutingHTTPServer dispatches to FBCommandHandler
4. FBCommandHandler → Command Module → Utilities → XCTest / Accessibility APIs
5. XCTest Reports → JSON Response → FBResponseJSONPayload
6. JSON Response → Tunnel → HTTP Proxy → Appium Client

##### Architectural Patterns & Design Principles
- Separation of Concerns:
- Build/deploy vs. session management vs. HTTP proxy vs. native server.
- Native side: routing layer (Routes → Handlers → Commands → System APIs).
- Event-driven / Request-Response: HTTP server handles each WebDriver call.
- Modularization:
- Node side: split into small utility modules, proxy, build.
- Native side: clearly separated Categories, Commands, Routing, Utilities, Vendor.
- Extensibility:
- New WebDriver endpoints can be added by creating new FB*Command classes and registering routes.

##### Technologies, Frameworks, Libraries
- Host Side:
- Node.js, TypeScript, npm modules, promise-based code
- Azure Pipelines / GitHub Actions for CI
- Device Side:
- Xcode project (Objective-C), XCTest, CocoaHTTPServer, RoutingHTTPServer
- Private Apple headers for accessibility & event generation
- Build Tools:
- Fastlane, xcodebuild, custom shell/js scripts

- Components
- Rectangles for logical modules (e.g., “Node HTTP Proxy”, “Build & Deploy”, “XCTest Runner”).
- Data Flow
- Host side (blue), Device side (green), Transport/tunnel (orange), Frameworks (grey).
- Labels & Annotations
- Clearly label ports, protocols (HTTP, USBMux).
- Where native frameworks (XCTest, Accessibility) are invoked.

##### Detail Level
- External dependencies (CocoaHTTPServer) under Vendor.
- CI/CD pipelines only if illustrating build automation. Otherwise, focus on runtime architecture.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Client
    AppiumClient["Appium Client"]:::external

    %% Host Side
    subgraph "Host (macOS) - Node.js Side"
        direction TB
        CLI["CLI / Entry Point\n(index.ts)"]:::host
        BuildDeploy["Build & Deployment Layer"]:::host
        XcodeBuild["xcodebuild Wrapper\n(lib/xcodebuild.js)"]:::host
        Scripts["Scripts/*"]:::host
        Proxy["HTTP Proxy Server\n(lib/webdriveragent.js,\nlib/no-session-proxy.js)"]:::host
        SessionMgmt["Proxy & Session Management\n(lib/webdriveragent.js,\nlib/no-session-proxy.js,\nlib/utils.js,\nlib/constants.js,\nlib/logger.js)"]:::host
    end

    %% Tunnel/Transport
    Tunnel["Tunnel / USBMux\n(Port Forwarding)"]:::tunnel

    %% Device Side
    subgraph "Device/Simulator - WDA Server"
        direction TB
        XCTestRunner["XCTest Runner\n(WebDriverAgentRunner)"]:::device
        NativeHTTP["Native HTTP Server & Routing\n(CocoaHTTPServer,\nRoutingHTTPServer)"]:::device
        RoutingLayer["Routing Layer\n(FBWebServer, FBRoute,\nFBCommandHandler,\nFBResponseJSONPayload,\nFBSession)"]:::device
        Commands["Command Modules\n(FBElementCommands,\nFBScreenshotCommands,\netc.)"]:::device
        UtilsCats["Utilities & Categories\n(FBElementHelpers,\nFBW3CActionsSynthesizer,\nFBLogger,\nCategories)"]:::device
        PrivateHdrs["Private Apple Headers\n(AccessibilityUtilities,\nXCTest)"]:::framework
        XCTestFrameworks["XCTest & Accessibility Frameworks"]:::framework
    end

    %% Connections - Build & Deploy Flow
    CLI -->|"invoke scripts"| Scripts
    Scripts -->|"calls xcodebuild"| XcodeBuild
    Scripts -->|"deploy WDA to device"| XCTestRunner
    XcodeBuild --> XCTestRunner

    %% Runtime Proxy Flow
    AppiumClient -->|"WebDriver JSON"| Proxy
    Proxy -->|"forward via"| Tunnel
    Tunnel -->|"HTTP request"| NativeHTTP
    NativeHTTP -->|"dispatch"| RoutingLayer
    RoutingLayer -->|"execute"| Commands
    Commands -->|"use"| UtilsCats
    UtilsCats -->|"call"| XCTestFrameworks
    RoutingLayer -->|"session track"| RoutingLayer
    Commands -->|"use private APIs"| PrivateHdrs
    RoutingLayer -->|"response JSON"| NativeHTTP
    NativeHTTP -->|"HTTP response"| Tunnel
    Tunnel -->|"response JSON"| Proxy
    Proxy -->|"WebDriver JSON"| AppiumClient

    %% Click Events - Host Side
    click CLI "https://github.com/qawolf/webdriveragent/blob/master/index.ts"
    click Scripts "https://github.com/qawolf/webdriveragent/blob/master/Scripts/build-webdriveragent.js"
    click Scripts "https://github.com/qawolf/webdriveragent/blob/master/Scripts/build.sh"
    click Scripts "https://github.com/qawolf/webdriveragent/blob/master/Scripts/ci/build-real.sh"
    click Scripts "https://github.com/qawolf/webdriveragent/blob/master/Scripts/ci/build-sim.sh"
    click Scripts "https://github.com/qawolf/webdriveragent/blob/master/Scripts/fetch-prebuilt-wda.js"
    click Scripts "https://github.com/qawolf/webdriveragent/blob/master/Scripts/update-wda-version.js"
    click XcodeBuild "https://github.com/qawolf/webdriveragent/blob/master/lib/xcodebuild.js"
    click Proxy "https://github.com/qawolf/webdriveragent/blob/master/lib/webdriveragent.js"
    click SessionMgmt "https://github.com/qawolf/webdriveragent/blob/master/lib/no-session-proxy.js"
    click SessionMgmt "https://github.com/qawolf/webdriveragent/blob/master/lib/utils.js"
    click SessionMgmt "https://github.com/qawolf/webdriveragent/blob/master/lib/constants.js"
    click SessionMgmt "https://github.com/qawolf/webdriveragent/blob/master/lib/logger.js"

    %% Click Events - Device Side
    click XCTestRunner "https://github.com/qawolf/webdriveragent/tree/master/WebDriverAgentRunner/"
    click XCTestRunner "https://github.com/qawolf/webdriveragent/blob/master/WebDriverAgentRunner/UITestingUITests.m"
    click NativeHTTP "https://github.com/qawolf/webdriveragent/tree/master/WebDriverAgentLib/Vendor/"
    click RoutingLayer "https://github.com/qawolf/webdriveragent/blob/master/WebDriverAgentLib/Routing/FBWebServer.h"
    click RoutingLayer "https://github.com/qawolf/webdriveragent/blob/master/WebDriverAgentLib/Routing/FBWebServer.m"
    click RoutingLayer "https://github.com/qawolf/webdriveragent/blob/master/WebDriverAgentLib/Routing/FBRoute.h"
    click RoutingLayer "https://github.com/qawolf/webdriveragent/blob/master/WebDriverAgentLib/Routing/FBRoute.m"
    click RoutingLayer "https://github.com/qawolf/webdriveragent/blob/master/WebDriverAgentLib/Routing/FBCommandHandler.h"
    click RoutingLayer "https://github.com/qawolf/webdriveragent/blob/master/WebDriverAgentLib/Routing/FBResponseJSONPayload.h"
    click RoutingLayer "https://github.com/qawolf/webdriveragent/blob/master/WebDriverAgentLib/Routing/FBResponseJSONPayload.m"
    click RoutingLayer "https://github.com/qawolf/webdriveragent/blob/master/WebDriverAgentLib/Routing/FBSession.h"
    click RoutingLayer "https://github.com/qawolf/webdriveragent/blob/master/WebDriverAgentLib/Routing/FBSession.m"
    click Commands "https://github.com/qawolf/webdriveragent/blob/master/WebDriverAgentLib/Commands/FBElementCommands.h"
    click Commands "https://github.com/qawolf/webdriveragent/blob/master/WebDriverAgentLib/Commands/FBElementCommands.m"
    click Commands "https://github.com/qawolf/webdriveragent/blob/master/WebDriverAgentLib/Commands/FBScreenshotCommands.h"
    click Commands "https://github.com/qawolf/webdriveragent/blob/master/WebDriverAgentLib/Commands/FBScreenshotCommands.m"
    click Commands "https://github.com/qawolf/webdriveragent/blob/master/WebDriverAgentLib/Commands/FBSessionCommands.h"
    click Commands "https://github.com/qawolf/webdriveragent/blob/master/WebDriverAgentLib/Commands/FBSessionCommands.m"
    click UtilsCats "https://github.com/qawolf/webdriveragent/blob/master/WebDriverAgentLib/Utilities/FBElementHelpers.h"
    click UtilsCats "https://github.com/qawolf/webdriveragent/blob/master/WebDriverAgentLib/Utilities/FBElementHelpers.m"
    click UtilsCats "https://github.com/qawolf/webdriveragent/blob/master/WebDriverAgentLib/Utilities/FBW3CActionsSynthesizer.h"
    click UtilsCats "https://github.com/qawolf/webdriveragent/blob/master/WebDriverAgentLib/Utilities/FBW3CActionsSynthesizer.m"
    click UtilsCats "https://github.com/qawolf/webdriveragent/blob/master/WebDriverAgentLib/Utilities/FBLogger.h"
    click UtilsCats "https://github.com/qawolf/webdriveragent/blob/master/WebDriverAgentLib/Utilities/FBLogger.m"
    click UtilsCats "https://github.com/qawolf/webdriveragent/tree/master/WebDriverAgentLib/Categories/"

    %% Styles
    classDef host fill:#D0E6FF,stroke:#000,stroke-width:1px;
    classDef device fill:#D0FFD6,stroke:#000,stroke-width:1px;
    classDef tunnel fill:#FFE6A3,stroke:#000,stroke-width:1px;
    classDef framework fill:#E0E0E0,stroke:#000,stroke-width:1px;
    classDef external fill:#F8F8F8,stroke:#000,stroke-width:1px;
```
