English | 简体中文

Kea2's logo: A large parrot skilled in finding "bugs"

📘 User Manual | 📘 用户手册

About

Kea2 is an easy-to-use tool for fuzzing mobile apps. Its key novelty is able to fuse automated UI testing with scripts (usually written by human), thus empowering automated UI testing with human intelligence for effectively finding crashing bugs as well as non-crashing functional (logic) bugs.

Kea2 is currently built on top of Fastbot 3.0 (a modified/enhanced version of the original FastBot 2.0), an industrial-strength automated UI testing tool from ByteDance, and uiautomator2, an easy-to-use and stable Android automation library. Kea2 currently targets Android apps.

Kea2_demo.mp4

Novelty & Important features

• Feature 1(查找稳定性问题): coming with the full capability of Fastbot for stress testing and finding stability problems (i.e., crashing bugs);

• Feature 2(自定义测试场景\事件序列\黑白名单\黑白控件¹): customizing testing scenarios when running Fastbot (e.g., testing specific app functionalities, executing specific event traces, entering specifc UI pages, reaching specific app states, blacklisting specific activities/UI widgets/UI regions) with the full capability and flexibility powered by python language and uiautomator2;

• Feature 3(支持断言机制²): supporting auto-assertions when running Fastbot, based on the idea of property-based testing inheritted from Kea, for finding logic bugs (i.e., non-crashing functional bugs).

  For Feature 2 and 3, Kea2 allows you to focus on what app functionalities to be tested. You do not need to worry about how to reach these app functionalities. Just let Fastbot help. As a result, your scripts are usually short, robust and easy to maintain, and the corresponding app functionalities are much more stress-tested!

The ability of the three features in Kea2

	Feature 1	Feature 2	Feature 3
Finding crashes	👍	👍	👍
Finding crashes in deep states		👍	👍
Finding non-crashing functional (logic) bugs			👍

Kea2's Users

Kea2 (and its idea) has been used/integrated by

• OPay Business --- a financial & payment app (20 millions of active users daily). OPay uses Kea2 for regression testing on POS machines and mobile devices.

• WeChat's iExplorer --- WeChat's in-house testing platform (coming with an interactive UI-based tool to ease writing scripts)

• WeChat Payment's UAT --- WeChat Payment's in-house testing platform (fully automated property-based testing by synthesizing properties from the system specifications)

• DevEco Testing --- Huawei's Official Testing Platform for HarmonyOS (Kea2 is built upon Hypium)

• ByteDance's Fastbot

Please let us know and willing to hear your feedback/questions if you are also using Kea2.

Design & Roadmap

Kea2 currently works with 3 open-sourced projects:

• unittest as the testing framework to manage the scripts;
• uiautomator2 as the UI test driver;
• Fastbot as the backend automated UI testing tool.

Several key features of Kea2 are inspired by Hypothesis, the property-based testing framework for Python.

In the future, Kea2 will be extended to support:

• pytest, another popular python testing framework;
• Appium, Hypium (for HarmonyOS/Open Harmony);
• any other automated UI testing tools (not limited to Fastbot)

Installation

Running environment:

• support Windows, MacOS and Linux
• python 3.8+, Android 5.0~16.0 (Android SDK installed)
• Disable localhost proxy (some VPNs affect u2). Set it to bypass localhost or turn off the VPN if needed. (Required for Features 2 and 3.)

Install Kea2 by pip:

python3 -m pip install kea2-python

Find Kea2's options by running

kea2 -h

Upgrade Kea2 to its latest version if you already installed Kea2 before:

python3 -m pip install -U kea2-python

If you're using mirror sites like Tsinghua or USTC, you may fail to upgrade. Because these sites may not have the latest version yet. In this case, you can try to install Kea2 by specifying the latest version manually, or use pypi.org directly by pip install kea2-python -i https://pypi.org/simple.

Upgrade Kea2 to the specifc latest version (e.g., 1.0.0) if you already installed Kea2 before:

python3 -m pip install -U kea2-python==1.0.0

Initialize Kea2 under your preferred working directory:

kea2 init

This initialization step is always needed if it is your first time to run Kea2. If you have upgraded Kea2, you are also recommended to rerun this step to ensure any potential new configurations of Kea2 would take effect.

Quick Test

Kea2 connects to and runs on Android devices. We recommend you to do a quick test to ensure that Kea2 is compatible with your devices.

1. Connect to a real Android device or an Android emulator and make sure you can see the connected device by running adb devices.

2. Run quicktest.py to test a sample app omninotes (released as omninotes.apk in Kea2's repository). The script quicktest.py will automatically install and test this sample app for a short time.

Run the quick test:

python3 quicktest.py

This quick test would automatically download omninotes.apk. If the download fails, please copy omninotes.apk from Kea2's repository (top-level) to your working directory and execute the quick test command again.

If you can see the app omninotes is successfully running and tested, Kea2 works! Otherwise, please help file a bug report with the error message to us. Thank you!

Feature 1 (Find crashes with the full capability of Fastbot and get kea2 test reports)

Test your app with the full capability of Fastbot for stress testing and finding stability problems (i.e., crashing bugs); Meanwhile, you can get test reports generated by Kea2 to understand app behaviors and discovered bugs during testing.

kea2 run -p it.feio.android.omninotes.alpha --running-minutes 10

To understand the meanings of the options, you can see our user manual.

The usage is similar to the the original Fastbot's shell commands.

See more options by

kea2 run -h

Feature 2 (Run Enhanced Fastbot: Custom Testing Scenarios/Event Sequences/Widget Whitelists and Blacklists)

When running any automated UI testing tools like Fastbot to test your apps, you may find that some specifc UI pages or functionalities are difficult to reach or cover. The reason is that Fastbot lacks knowledge of your apps. Fortunately, this is the strength of script testing. In Feature 2, Kea2 can support writing small scripts to guide Fastbot to explore wherever we want. You can also use such small scripts to block specific widgets during UI testing.

In Kea2, a script is composed of two elements:

• Precondition: When to execute the script.
• Interaction scenario: The interaction logic (specified in the script's test method) to reach where we want.

Simple Example

Assuming Privacy is a hard-to-reach UI page during automated UI testing. Kea2 can easily guide Fastbot to reach this page.

    @prob(0.5)
    # precondition: when we are at the page `Home`
    @precondition(lambda self: 
        self.d(text="Home").exists
    )
    def test_goToPrivacy(self):
        """
        Guide Fastbot to the page `Privacy` by opening `Drawer`, 
        clicking the option `Setting` and clicking `Privacy`.
        """
        self.d(description="Drawer").click()
        self.d(text="Settings").click()
        self.d(text="Privacy").click()

• By the decorator @precondition, we specify the precondition --- when we are at the Home page. In this case, the Home page is the entry page of the Privacy page and the Home page can be easily reached by Fastbot. Thus, the script will be activated when we are at Home page by checking whether a unique widget Home exists.
• In script's test method test_goToPrivacy, we specify the interaction logic (i.e., opening Drawer, clicking the option Setting and clicking Privacy) to guide Fastbot to reach the Privacy page.
• By the decorator @prob, we specify the probability (50% in this example) to do the guidance when we are at the Home page. As a result, Kea2 still allows Fastbot to explore other pages.

You can find the full example in script quicktest.py, and run this script with Fastbot by the command kea2 run:

# Launch Kea2 and load one single script quicktest.py.
kea2 run -p it.feio.android.omninotes.alpha --running-minutes 10 propertytest discover -p quicktest.py

Feature 3 (Run Enhanced Fastbot: Add Assertions)

Kea2 supports auto-assertions when running Fastbot for finding logic bugs (i.e., non-crashing bugs). To achieve this, you can add assertions in the scripts. When an assertion fails during automated UI testing, we find a likely functional bug.

In Feature 3, a script is composed of three elements:

• Precondition: When to execute the script.
• Interaction scenario: The interaction logic (specified in the script's test method).
• Assertion: The expected app behaviour.

Example

In a social media app, message sending is a common feature. On the message sending page, the send button should always appears when the input box is not empty (i.e., has some message).

The expected behavior (the upper figure) and the buggy behavior (the lower figure).

​

For the preceding always-holding property, we can write the following script to validate the functional correctness: when there is an input_box widget on the message sending page, we can type any non-empty string text into the input box and assert send_button should always exists.

    @precondition(
        lambda self: self.d(description="input_box").exists
    )
    def test_input_box(self):

        # genenerate a random non-empty string (this is also property-based testing
        #                                       by feeding random text inputs!)
        from hypothesis.strategies import text, ascii_letters
        random_str = text(alphabet=ascii_letters).example()

        # input this non-empty string into the input box 
        self.d(description="input_box").set_text(random_str)

        # check whether the send button exists
        assert self.d(description="send_button").exist

        # we can even do more assertions, e.g.,
        #       the input string should successfully appear on the message sending page
        assert self.d(text=random_str).exist

We use hypothesis to generate random texts.

You can run this example by using the similar command line in Feature 2.

Test Reports

Kea2 automatically generates a HTML test report after each testing session. You can find the report in output/ under your working directory.

Sample test reports

• Single test report - Courtesy of Opay.
• Merged test report (multiple runs) - Summary for multiple runs.

You can find more details on the test report in this documentation.

📘 User Manual (用户手册)

Please see the user manual for more details on how to use Kea2.

请查看用户手册以获取更多Kea2的详细文档。

📣 News & Media

• Property-driven Testing Technology: Next-generation GUI Automated Testing - Video replay and slides @ MTSC 2025
• Let's GoSSIP 2025 Software Security Summer School: Kea2 (Preview #1)

Industry perspectives on Kea2 (click to expand, courtesy of Opay):

What does a “property” mean in Kea2? What is Kea2's value?

Kea2 is essentially a toolkit that combines Python, uiautomator2, and Fastbot. It is like a vehicle chassis with an engine and wheels already assembled.

The concept of “property” was introduced by Prof. Su's team. In practical testing work, a property corresponds to a minimal, atomic app function with little or no dependency on other flows, so it can run independently. Typical examples include login (enter username, enter password, submit) or liking a video with just a few steps.

The value of combining properties with Kea2 is that it addresses the “heavy scripting” issue in Appium-style tests. With Appium, testing one property often requires many lines of navigation code. With Kea2, you mainly define the property itself, and Fastbot plus its learning strategy handles how to reach the target state.

Another major value is technical enablement: Kea2 provides lighter UI scripting than Appium, while compensating for Fastbot's original limitations in property logic and assertions. It preserves Fastbot's strengths and fills key capability gaps.

In short, for strictly orchestrated functional test cases, Appium is still a fine choice. But if your goal is exploratory testing, fuzz/stress testing, or compatibility testing, Kea2 is strongly recommended.

What is Kea2 made of? What is its core role? What has it changed?

Kea2 is composed of:

Fastbot -- the fuzzing engine that drives large-scale exploration.
u2 -- executes business-level UI actions, similar in spirit to Selenium/Appium interactions.
Python -- used to write UI actions, logic, and custom behaviors.

Kea2's core role:

It provides condition triggers. While Fastbot is exploring, Kea2 continuously evaluates trigger conditions. When a condition is met, Fastbot is paused, the specified UI test/assertions are executed, and then control returns to Fastbot.

What Kea2 has changed:

Replaced Fastbot's original condition-trigger mechanism.
Replaced Fastbot's activity/widget blacklist mechanism.
Replaced Fastbot's pruning mechanism.
Added richer element-space operation capabilities.
Added logic modeling in fuzz testing workflows.
Added assertion support.
Expanded UI element interaction capabilities.

Relevant papers of Kea2

General and Practical Property-based Testing for Android Apps. ASE 2024. pdf

An Empirical Study of Functional Bugs in Android Apps. ISSTA 2023. pdf

Fastbot2: Reusable Automated Model-based GUI Testing for Android Enhanced by Reinforcement Learning. ASE 2022. pdf

Guided, Stochastic Model-Based GUI Testing of Android Apps. ESEC/FSE 2017. pdf

Contact us

Please contact Xixian Liang at xixian@stu.ecnu.edu.cn with your Wechat ID / QR code to be invited to the WeChat discussion group.

Of course, we are also ready on GitHub to answer your questions/feedback.

Maintainers/Contributors

Kea2 has been actively developed and maintained by the people in ecnusse:

• Xixian Liang (@XixianLiang)
• Bo Ma (@majuzi123)
• Cheng Peng (@Drifterpc)
• Ting Su (@tingsu)

Zhendong Su, Yiheng Xiong, Xiangchen Shen, Mengqian Xu, Haiying Sun, Jingling Sun, Jue Wang, Geguang Pu have also been actively participated in this project and contributed a lot!

Kea2 has also received many valuable insights, advices, feedbacks and lessons shared by several industrial people from Bytedance (Zhao Zhang, Yuhui Su from the Fastbot team), OPay (Tiesong Liu), WeChat (Haochuan Lu, Yuetang Deng), Huawei, Xiaomi and etc. Kudos!

Become a Contributor!

Kea2 is an open-source project and we are calling for more contributors to join us!

See Developer guide for more details.

Star History

Footnotes

1. Many UI automated testing tools provide “custom event sequence” features (such as Fastbot and AppCrawler), but these features often have practical limitations, such as restricted flexibility and difficult maintenance. Many Fastbot users have reported issues with its custom event sequence capability, e.g., #209, #225, and #286. ↩

2. Supporting automatic assertions during UI automated testing is an important capability, but very few tools provide it. We noticed that the developers of AppCrawler once planned to introduce an assertion mechanism; the idea received strong user interest, and users kept asking for updates since 2021, but it has not been delivered. ↩