# ecnusse/kea2 architecture

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

- Interactive diagram: https://gitdiagram.com/ecnusse/kea2
- Repository: https://github.com/ecnusse/kea2

## Overview

##### Project Type and Purpose
- Type: A Python-based CLI library/tool for automated UI testing of Android apps
- Purpose: Integrate Fastbot (stress/fuzz testing) + uiautomator2 (scripted UI interactions) + property-based assertions into one unified framework (Kea2)

##### File Structure and README Insights
Top-level:
- kea2/         – core library and modules
- quickstart.py, quickstart2.py, quicktest.py – sample entry scripts
- pyproject.toml – packaging/build
- tests/        – integration tests and emulator scripts
- assets under kea2/assets – jars, configs, third-party libs
Key modules:
- kea2/cli.py        – CLI parsing & entrypoints
- kea2/kea_launcher.py – initializes Options, drivers, test runner
- kea2/absDriver.py, u2Driver.py – driver abstraction for devices
- kea2/adbUtils.py   – helper for adb commands
- kea2/logWatcher.py – monitors device logs for crashes
- kea2/keaUtils.py, utils.py – decorators (“@precondition”, “@prob”), script loading
- kea2/assets        – Fastbot jars, configs, scripts for injection

##### Main Architectural Components
A. CLI Layer
– kea2 command (`kea2 -h`, `kea2 run`) implemented in kea2/cli.py
– quicktest.py, quickstart.py as Python entry scripts
B. Launcher & Core Engine
– kea2/kea_launcher.py orchestrates:
- parse CLI args → Options object
- instantiate driver (U2Driver or native)
- configure Fastbot via config files in assets
- hook into unittest (KeaTestRunner)
C. Script/Test Layer
– User’s tests (unittest TestCase methods)
– Decorators in kea2/keaUtils.py for preconditions & probabilities
– Scripts perform interactions (self.d(...)) and assertions
D. Driver Layer
– absDriver.py defines interface
– u2Driver.py implements methods over uiautomator2
– adbUtils.py for shell calls (install APK, start emulator, etc.)
E. Fastbot & Uiautomator2 (External Services)
– Fastbot backend (fastbot-thirdpart.jar executed on device)
– uiautomator2 Python library on host & corresponding .jar on device
F. Device Under Test
– Physical Android device or emulator
– Kea2 pushes assets (Fastbot libs, framework.jar, monkeyq.jar)
G. Log & Result Collection
– logWatcher.py tails `adb logcat` for crash detection
– output_dir/result.json with execution statistics

##### Component Interactions & Data Flow
1) User invokes CLI →
2) CLI parses and calls KeaLauncher →
3) KeaLauncher loads Options, deploys assets to device via adbUtils →
4) Starts Fastbot agent on device (native) or spawns uiautomator2 session →
5) Discovers and schedules test methods (scripts) via unittest/KeaTestRunner →
6) For each test:
- Check @precondition → call driver APIs (d.click(), d.set_text(), …)
- Driver (u2Driver) translates to uiautomator2 calls or shell monkey events
- Property-based assertions evaluated in Python
7) logWatcher continuously reads crash logs → flags test failures
8) Test results and statistics written to output_dir/result.json

##### Architectural Patterns & Principles
- Plugin-style driver abstraction (absDriver → u2Driver or native)
- Use of Python decorators to inject testing logic (precondition, probability)
- Separation of concerns: CLI / Launcher / Test Scheduling / Driver / Logging
- Integration with standard unittest framework for script discovery

## Diagram (Mermaid)

```mermaid
graph TB
    %% CLI Layer
    subgraph "CLI Layer"
        CLI["CLI (kea2)"]:::host
        QS1["quickstart.py"]:::host
        QS2["quickstart2.py"]:::host
        QT["quicktest.py"]:::host
    end

    %% Launcher & Core Engine
    subgraph "Launcher & Core Engine"
        KL["KeaLauncher"]:::host
    end

    %% Script/Test Layer
    subgraph "Script/Test Layer"
        KU["keaUtils"]:::host
        UTL["utils"]:::host
        TS["Test Scripts (unittest)"]:::host
    end

    %% Driver Layer
    subgraph "Driver Layer"
        AD["absDriver"]:::host
        U2["u2Driver"]:::host
        AU["adbUtils"]:::host
    end

    %% External Services & Assets
    subgraph "External Services & Assets"
        FBJ["fastbot-thirdpart.jar"]:::assets
        FBC["fastbot_configs"]:::assets
        FBL["fastbot_libs"]:::assets
        U2J["u2.jar"]:::assets
        UA["uiautomator2 Python lib"]:::external
    end

    %% Device Under Test
    subgraph "Device Under Test"
        APK["omninotes.apk"]:::device
        FBA["Fastbot Agent"]:::device
        U2A["uiautomator2 .jar"]:::device
    end

    %% Log & Result Collection
    subgraph "Log & Result Collection"
        LW["logWatcher"]:::host
        R["result.json"]:::host
    end

    %% Connections
    CLI -->|invokes| KL
    QS1 -->|invokes| KL
    QS2 -->|invokes| KL
    QT -->|invokes| KL

    KL -->|loads decorators| KU
    KL -->|loads utils| UTL
    KL -->|schedules| TS

    TS -->|use| KU
    TS -->|use| UTL
    TS -->|invoke driver| AD
    TS -->|invoke driver| U2

    KL -->|instantiate| AD
    KL -->|instantiate| U2
    KL -->|configure| AU

    AD -->|calls| AU
    U2 -->|calls| AU

    KL -->|deploys assets| APK
    KL -->|deploys| FBJ
    KL -->|deploys| FBC
    KL -->|deploys| FBL
    KL -->|deploys| U2J

    AU -->|install/start| APK
    U2 -->|start session| U2A
    AD -->|start agent| FBA
    U2 -->|use lib| UA

    FBA -->|logs| LW
    U2A -->|logs| LW

    LW -->|writes| R
    TS -->|writes| R

    %% Click Events
    click CLI "https://github.com/ecnusse/kea2/blob/main/kea2/cli.py"
    click QS1 "https://github.com/ecnusse/kea2/blob/main/quickstart.py"
    click QS2 "https://github.com/ecnusse/kea2/blob/main/quickstart2.py"
    click QT "https://github.com/ecnusse/kea2/blob/main/quicktest.py"
    click KL "https://github.com/ecnusse/kea2/blob/main/kea2/kea_launcher.py"
    click KU "https://github.com/ecnusse/kea2/blob/main/kea2/keaUtils.py"
    click UTL "https://github.com/ecnusse/kea2/blob/main/kea2/utils.py"
    click TS "https://github.com/ecnusse/kea2/tree/main/tests/"
    click AD "https://github.com/ecnusse/kea2/blob/main/kea2/absDriver.py"
    click U2 "https://github.com/ecnusse/kea2/blob/main/kea2/u2Driver.py"
    click AU "https://github.com/ecnusse/kea2/blob/main/kea2/adbUtils.py"
    click FBJ "https://github.com/ecnusse/kea2/blob/main/kea2/assets/fastbot-thirdpart.jar"
    click FBC "https://github.com/ecnusse/kea2/tree/main/kea2/assets/fastbot_configs/"
    click FBL "https://github.com/ecnusse/kea2/tree/main/kea2/assets/fastbot_libs/"
    click U2J "https://github.com/ecnusse/kea2/blob/main/kea2/assets/u2.jar"
    click LW "https://github.com/ecnusse/kea2/blob/main/kea2/logWatcher.py"

    %% Styles
    classDef host fill:#D6EAF8,stroke:#1B4F72,stroke-width:1px
    classDef external fill:#A9DFBF,stroke:#196F3D,stroke-width:1px
    classDef device fill:#F5B7B1,stroke:#78281F,stroke-width:1px
    classDef assets fill:#E5E7E9,stroke:#566573,stroke-width:1px
```
