How ecnusse/kea2 works
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