# openatx/uiautomator2 architecture

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

- Interactive diagram: https://gitdiagram.com/openatx/uiautomator2
- Repository: https://github.com/openatx/uiautomator2

## Overview

##### Project type and purpose
- This is not a web‑app or full‑stack site but an open‑source Python client library and CLI called “uiautomator2.”
- Its purpose is to let testers and automation engineers write Python code on their computer that drives Android UiAutomator2 APIs running on a real device (or emulator).

##### File structure
- Top‑level modules and files:
- uiautomator2/ – the core Python package (core.py, _proto.py for JSON‑RPC, modules for input, swipe, xpath, watcher, etc.)
- __main__.py – CLI entrypoint
- examples/ – sample scripts (Python, Go, JS) showing usage patterns
- demo_tests/, mobile_tests/, tests/ – pytest‑based unit and integration tests
- docs/, README*.md – Sphinx and Markdown documentation
- uibox/ – a companion Go‑based CLI tool for health‑checking HTTP endpoints or other utilities
- CI/config: GitHub workflows, Makefile, pyproject.toml, poetry.toml

##### README for additional insights
- The library installs an Android‑side APK (android‑uiautomator‑server) via ADB, then uses ADB port forwarding so Python code can send HTTP JSON‑RPC calls to the server.
- It depends on adbutils for transport, Pillow or OpenCV for image screenshots, and optional modules under ext/ for HTML reports or performance data.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Python Client Library & CLI
    subgraph "Python uiautomator2 Client"
        Core["Core API (core.py)"]:::pythonComp
        Proto["JSON-RPC Client (_proto.py)"]:::pythonComp
        Input["Input Module (_input.py)"]:::pythonComp
        Selector["Selector Engine (_selector.py)"]:::pythonComp
        XPath["XPath Support (xpath.py)"]:::pythonComp
        Swipe["Swipe Actions (swipe.py)"]:::pythonComp
        Watcher["Watcher (watcher.py)"]:::pythonComp
        Screenrec["Screen Recording (screenrecord.py)"]:::pythonComp
        Image["Image Handling (image.py)"]:::pythonComp
        Settings["Settings Management (settings.py)"]:::pythonComp
        Utils["Utility Functions (utils.py)"]:::pythonComp
        Excp["Exception Definitions (exceptions.py)"]:::pythonComp
        Abs["Abstract Base Classes (abstract.py)"]:::pythonComp
        Version["Version Info (version.py)"]:::pythonComp
        CLI["CLI Entry (__main__.py)"]:::pythonComp
    end

    %% Extensions
    subgraph "Plugins / Extensions"
        HR["HTML Report Extension"]:::extComp
        Perf["Performance Data Extension"]:::extComp
    end

    %% ADB and Android
    subgraph "ADB Transport & Android Device"
        Transport["ADB Transport (adbutils)"]:::transportComp
        APK["Android Server APK"]:::androidComp
    end

    %% Examples & Tests
    subgraph "Examples & Test Suites"
        Examples["Sample Scripts (examples/)"]:::testComp
        DemoTests["Demo Test Suite (demo_tests/)"]:::testComp
        MobileTests["Mobile Integration Tests (mobile_tests/)"]:::testComp
        UnitTests["Unit & Unit/Integration Tests (tests/)"]:::testComp
    end

    %% Companion Tool
    subgraph "Companion Go Tool"
        UIBox["uibox (Go CLI)"]:::goComp
    end

    %% Data Flows and Relationships
    CLI -->|"uses core API"| Core
    Core -->|"wraps JSON-RPC"| Proto
    Core -->|"provides gestures & events"| Input
    Core -->|"provides selector engine"| Selector
    Core -->|"provides XPath support"| XPath
    Core -->|"provides swipe actions"| Swipe
    Core -->|"provides watchers"| Watcher
    Core -->|"provides screen recording"| Screenrec
    Core -->|"provides screenshots"| Image
    Core -->|"provides settings"| Settings
    Core -->|"provides utils"| Utils
    Core -->|"raises exceptions"| Excp
    Core -->|"defines base classes"| Abs
    Core -->|"exposes version"| Version

    CLI -->|"loads extensions"| HR
    CLI -->|"loads extensions"| Perf

    CLI -->|"executes transport commands"| Transport
    Transport -->|"forwards port"| APK
    Proto -->|"HTTP JSON-RPC"| APK
    APK -->|"invokes UiAutomator2 APIs"| APK

    Examples -->|"demonstrate usage of"| CLI
    DemoTests -->|"drive tests via"| CLI
    MobileTests -->|"drive tests via"| CLI
    UnitTests -->|"import and test"| Core

    UIBox -->|"uses transport"| Transport
    UIBox -->|"health checks via RPC"| APK

    %% Click Events
    click Core "https://github.com/openatx/uiautomator2/blob/master/uiautomator2/core.py"
    click Proto "https://github.com/openatx/uiautomator2/blob/master/uiautomator2/_proto.py"
    click Input "https://github.com/openatx/uiautomator2/blob/master/uiautomator2/_input.py"
    click Selector "https://github.com/openatx/uiautomator2/blob/master/uiautomator2/_selector.py"
    click XPath "https://github.com/openatx/uiautomator2/blob/master/uiautomator2/xpath.py"
    click Swipe "https://github.com/openatx/uiautomator2/blob/master/uiautomator2/swipe.py"
    click Watcher "https://github.com/openatx/uiautomator2/blob/master/uiautomator2/watcher.py"
    click Screenrec "https://github.com/openatx/uiautomator2/blob/master/uiautomator2/screenrecord.py"
    click Image "https://github.com/openatx/uiautomator2/blob/master/uiautomator2/image.py"
    click Settings "https://github.com/openatx/uiautomator2/blob/master/uiautomator2/settings.py"
    click Utils "https://github.com/openatx/uiautomator2/blob/master/uiautomator2/utils.py"
    click Excp "https://github.com/openatx/uiautomator2/blob/master/uiautomator2/exceptions.py"
    click Abs "https://github.com/openatx/uiautomator2/blob/master/uiautomator2/abstract.py"
    click Version "https://github.com/openatx/uiautomator2/blob/master/uiautomator2/version.py"
    click UIBox "https://github.com/openatx/uiautomator2/tree/master/uibox/"
    click HR "https://github.com/openatx/uiautomator2/tree/master/uiautomator2/ext/htmlreport/"
    click Perf "https://github.com/openatx/uiautomator2/tree/master/uiautomator2/ext/perf/"
    click Examples "https://github.com/openatx/uiautomator2/tree/master/examples/"
    click DemoTests "https://github.com/openatx/uiautomator2/tree/master/demo_tests/"
    click MobileTests "https://github.com/openatx/uiautomator2/tree/master/mobile_tests/"
    click UnitTests "https://github.com/openatx/uiautomator2/tree/master/tests/"

    %% Styles
    classDef pythonComp fill:#f3f7fa,stroke:#0366d6;
    classDef extComp fill:#e5f5e0,stroke:#31a354;
    classDef transportComp fill:#fff5eb,stroke:#e6550d;
    classDef androidComp fill:#f0f0f0,stroke:#6a737d;
    classDef testComp fill:#fff5f0,stroke:#d73a49;
    classDef goComp fill:#edf2f7,stroke:#3182ce;
```
