Kea2 is a mobile application fuzzing framework designed to detect both crashing bugs and non-crashing functional bugs in Android applications. It achieves this by fusing automated UI testing with human-written test scripts, enabling developers to leverage the exploratory power of automated fuzzing while incorporating domain-specific knowledge through custom test logic.
This page provides a high-level introduction to Kea2's architecture, components, and operating principles. For specific features, see Four Testing Features. For detailed architectural internals, see Architecture Deep Dive. For practical usage instructions, see User Guide.
Sources: README.md23-36 README.md38-61
Traditional mobile testing approaches face significant limitations:
| Approach | Strengths | Weaknesses |
|---|---|---|
| Pure Automated Testing (e.g., Fastbot) | Explores app states exhaustively; finds stability bugs | Cannot detect logic bugs; lacks domain knowledge; struggles with deep app states |
| Pure Script Testing (e.g., Appium, uiautomator2) | Encodes domain knowledge; can check assertions | Requires explicit navigation to target states; brittle to UI changes; labor-intensive |
Kea2 addresses these limitations by enabling scripts to act as conditional guides for automated exploration: scripts activate only when specific preconditions are met during fuzzing, allowing Fastbot to handle navigation while developers focus on defining important properties to test.
Sources: README.md48-52 README.md165-169
Kea2's core innovation is property-based testing with preconditions, structured as follows:
Testing Flow:
This approach allows short, maintainable scripts that focus on what to test rather than how to reach the test state.
Sources: README.md167-195 docs/manual_en.md17-52
Kea2 is built on three foundational technologies:
| Component | Role | Version |
|---|---|---|
| Fastbot | Backend fuzzing engine providing random exploration and crash detection | Modified Fastbot 3.0 |
| uiautomator2 | Android UI automation library for script execution | Latest stable |
| unittest | Python testing framework managing test discovery and execution | Python 3.8+ stdlib |
Sources: README.md79-88 README.md90-95 kea2/core/testRunner.py1-50
Kea2's architecture is organized into five logical layers:
1. User Interface Layer
kea2 init, kea2 run, kea2 report, kea2 merge)KeaTestRunnerunittest.TestCase classes with Kea2 decorators2. Core Orchestration Layer
3. Execution Engine Layer
monkeyq.jar, manages HTTP API communication4. Device Communication Layer
5. Reporting Layer
Sources: README.md79-88 Diagram 1 from provided system diagrams
Kea2 supports multiple testing modes through its flexible driver architecture:
| Mode | Purpose | Connection | Side Effects | Use Case |
|---|---|---|---|---|
| Static Mode | Precondition evaluation | Cached XML hierarchy | None | Check if @precondition is satisfied without affecting app state |
| Script Mode (Proxy) | Test execution during fuzzing | Port 8090 via Fastbot HTTP server | Yes | Execute test scripts while maintaining Fastbot context |
| Script Mode (Direct) | Test execution standalone | Port 9008 direct to uiautomator2 | Yes | Run tests without Fastbot (Feature 4: hybrid mode) |
uiautomator2.Device instancesSources: kea2/u2Driver/u2Driver.py1-100 Diagram 4 from provided system diagrams
The complete test execution follows this sequence:
Key Stages:
@precondition decorators using static modeSources: Diagram 2 from provided system diagrams, kea2/core/testRunner.py100-500
Kea2 uses a project-based configuration model:
| File | Purpose | User-Editable |
|---|---|---|
configs/version.json | Records initialization version | No (auto-generated) |
configs/widget.block.py | Widget/tree blocking rules | Yes |
configs/awl.strings | Activity whitelist | Yes |
configs/abl.strings | Activity blacklist | Yes |
config_version.json (system) | Current Kea2 config schema version | No (in package) |
The ConfigVersionSanitizer (kea2/version/versionController.py) ensures configuration compatibility:
configs/version.json against system's config_version.jsonSources: README.md118-124 docs/manual_en.md390-399 Diagram 5 from provided system diagrams
Kea2 runs on the host machine (developer's computer) and communicates with the Android device (physical or emulator) via ADB:
Sources: README.md90-95 README.md128-142
Kea2 extends Python's unittest framework with custom decorators:
| Decorator | Purpose | Example |
|---|---|---|
@precondition | Define when test activates | @precondition(lambda self: self.d(text="Home").exists) |
@prob | Execution probability (0.0-1.0) | @prob(0.7) |
@max_tries | Limit execution count | @max_tries(5) |
@interruptable | Allow Fastbot interruption | @interruptable() (Feature 4) |
Implementation:
Sources: docs/manual_en.md56-101 README.md175-195
Kea2 tracks detailed execution statistics for each test method:
| Metric | Description | File |
|---|---|---|
precond_satisfied | Times precondition was true during exploration | result_*.json |
executed | Times test method actually ran | result_*.json |
fail | Times assertions failed (logic bugs found) | result_*.json |
error | Times test raised exceptions (script issues) | result_*.json |
JsonResult (kea2/core/result.py):
PropStatistic objectsresult_*.jsonPropertyExecutionInfo (kea2/core/result.py):
property_exec_info_*.jsonMixin Architecture (kea2/result/bugReportGenerator.py):
PathParserMixin: Parses event timeline from steps.logCrashAnrMixin: Deduplicates crash/ANR events from crash-dump.logScreenshotsMixin: Processes and marks screenshots with interaction indicatorsSources: docs/manual_en.md358-384 docs/manual_en.md263-309 Diagram 6 from provided system diagrams
Kea2 is actively used in production by multiple organizations:
| Organization | Application | Scale |
|---|---|---|
| OPay Business | Regression testing on POS and mobile devices | 2M+ daily active users |
| WeChat iExplorer | In-house testing platform with UI-based script authoring | - |
| WeChat Payment UAT | Automated property synthesis from specifications | - |
| Huawei DevEco Testing | Official HarmonyOS testing platform (built on Hypium) | - |
| ByteDance Fastbot | Integration with Fastbot ecosystem | - |
Sources: README.md62-76
For deeper understanding of specific Kea2 subsystems, consult these wiki sections:
Sources: Table of contents from provided JSON
Refresh this wiki