Kea2-python 1.0.2__tar.gz → 1.0.4__tar.gz

{kea2_python-1.0.2 → kea2_python-1.0.4}/Kea2_python.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: Kea2-python
-Version: 1.0.2
+Version: 1.0.4
 Summary: A python library for supporting and customizing automated UI testing for mobile apps
 Author-email: Xixian Liang <xixian@stu.ecnu.edu.cn>
 Requires-Python: >=3.8
@@ -26,8 +26,11 @@ Dynamic: license-file
 
 Please contact Xixian Liang at [xixian@stu.ecnu.edu.cn](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.
 
-### Github repo link
-[https://github.com/ecnusse/Kea2](https://github.com/ecnusse/Kea2)
+####  Github repo [https://github.com/ecnusse/Kea2](https://github.com/ecnusse/Kea2)
+####  Gitee mirror [https://gitee.com/XixianLiang/Kea2](https://gitee.com/XixianLiang/Kea2)
+
+
+
 
 ### [点击此处：查看中文文档](README_cn.md) 
 
@@ -43,7 +46,7 @@ Please contact Xixian Liang at [xixian@stu.ecnu.edu.cn](xixian@stu.ecnu.edu.cn)
 
 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](https://github.com/bytedance/Fastbot_Android), *an industrial-strength automated UI testing tool*, and [uiautomator2](https://github.com/openatx/uiautomator2), *an easy-to-use and stable Android automation library*.
+Kea2 is currently built on top of [Fastbot](https://github.com/ecnusse/Fastbot_Android) 3.0 (a modified/enhanced version of the original [FastBot](https://github.com/bytedance/Fastbot_Android) 2.0), *an industrial-strength automated UI testing tool from ByteDance*, and [uiautomator2](https://github.com/openatx/uiautomator2), *an easy-to-use and stable Android automation library*. 
 Kea2 currently targets [Android](https://en.wikipedia.org/wiki/Android_(operating_system)) apps. 
 
 ## Novelty & Important features
@@ -90,7 +93,7 @@ Please let us know and willing to hear your feedback/questions if you are also u
 Kea2 currently works with:
 - [unittest](https://docs.python.org/3/library/unittest.html) as the testing framework to manage the scripts;
 - [uiautomator2](https://github.com/openatx/uiautomator2) as the UI test driver; 
-- [Fastbot](https://github.com/bytedance/Fastbot_Android) as the backend automated UI testing tool.
+- [Fastbot](https://github.com/bytedance/Fastbot_Android) as the backend automated UI testing tool. 
 
 In the future, Kea2 will be extended to support
 - [pytest](https://docs.pytest.org/en/stable/), another popular python testing framework;
@@ -208,7 +211,7 @@ You can find the full example in script `quicktest.py`, and run this script with
 
 ```bash
 # Launch Kea2 and load one single script quicktest.py.
-kea2 run -p it.feio.android.omninotes.alpha --agent u2 --running-minutes 10 --throttle 200 --driver-name d propertytest discover -p quicktest.py
+kea2 run -p it.feio.android.omninotes.alpha --running-minutes 10 --throttle 200 --driver-name d propertytest discover -p quicktest.py
 ```
 
 ## Feature 3(运行增强版Fastbot：加入自动断言)
@@ -243,7 +246,8 @@ For the preceding always-holding property, we can write the following script to
     )
     def test_input_box(self):
 
-        # genenerate a random non-empty string (this is also property-based testing by feeding random text inputs!)
+        # 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()
 
@@ -261,9 +265,7 @@ For the preceding always-holding property, we can write the following script to
 
 You can run this example by using the similar command line in Feature 2.
 
-## Feature 4 (Experimental feature, 实验中，脚本与遍历的混合测试)
-
-> This feature is still under development. We are looking forward to your feedback! Contact us if you're interested in this feature.
+## Feature 4(兼容已有脚本：通过前置脚本步骤到达特定层次)
 
 Kea2 supports reusing existing Ui test Scripts. We are inspired by the idea that: *The existing Ui test scripts usually cover important app functionalities and can reach deep app states. Thus, they can be used as good "guiding scripts" to drive Fastbot to explore important and deep app states.*
 
@@ -271,22 +273,54 @@ For example, you may already have some existing Ui test scripts "login and add a
 
 ### Example
 
-See [guide_scripts.py](guide_scripts.py) for a full example.
+Here are four example scripts in hybridetest_examples, each corresponding to different forms of user scripts, showing you how to launch kea2 in the existing code.
 
-By the decorator `@interruptable`, you can mark the testcase as "interruptable" so that Kea2 can recognize this script and launch fuzzing test after it returns. 
+Specifically:  
 
-Since the state of app is probably unpredicted after fuzzing tests, Kea2 provides a `common_teardown` function to clean up the environment between previous script and next script. The function can be manually specified in `configs/teardown.py`.
+* [u2_unittest_example.py](hybridtest_examples\u2_unittest_example.py) is a u2 script organized with unittest.
+* [u2_pytest_example.py](hybridtest_examples\u2_pytest_example.py) is a u2 script organized with pytest.
+* [appium_unittest_example.py](hybridtest_examples\appium_unittest_example.py) is an appium script organized with unittest.
+* [appium_pytest_example.py](hybridtest_examples\appium_pytest_example.py) is an appium script organized with pytest.
 
-You can find the full example in `guide_scripts.py`, `property_omninotes.py`  and `configs/teardown.py` .  You can run one of the following commands:
+Some notes:
 
-```bash
-# Guide with guide_scripts.py and launch fuzzing test after every script.
-kea2 run -p it.feio.android.omninotes.alpha --agent u2 --running-minutes 10 --throttle 500 --max-step 15 --driver-name d unittest discover -p guide_scripts.py 
+1. You can control whether to execute the kea2-related code you have written by modifying the condition of 'if'. This allows you to easily enable or disable kea2 operations in the same script. Here we use environment variable as an example.
+2. Since kea2 is driven by u2, if an appium-written script wants to launch kea2, it is necessary to first close the appium session. Remember to configure the parameter `"noReset": True` in `desired_caps` to avoid resetting the application when closing the session.
+3. You need to insert the following code template into your existing test cases: Here, you can add your own hook logic in the commented sections, including starting or stopping the appium session, cleaning up instances, etc. This depends on how you want to design the setup and teardown. Apart from that, you only need to configure the `option` parameter and `configs_path` parameter(where your directory `configs` located, btw, `configs`'s location dependon where you executed `kea2 init`), then pass it to the `run_kea2_testing` function.
 
-# Guide with guide_scripts.py and launch fuzzing test after every script(check properties during fuzzing).
-kea2 run -p it.feio.android.omninotes.alpha --agent u2 --running-minutes 10 --throttle 500 --max-step 15 --driver-name d unittest discover -p guide_scripts.py propertytest discover -p quickstart2.py
+```python
+from kea2 import Kea2Tester, Options, U2Driver
+
+if os.environ.get('KEA2_HYBRID_MODE', '').lower() == 'true': 
+    '''
+    Note: The if condition here can be modified as needed according to the actual 
+    situation of the project, the form of environment variables is just an example.    
+    '''
+
+    # close your driver session etc. here
+    # ...
+    
+    tester = Kea2Tester()
+    result = self.tester.run_kea2_testing(
+        Options(
+            driverName="d",
+            packageNames=[PACKAGE_NAME],
+            propertytest_args=["discover", "-p", "Omninotes_Sample.py"],
+            serial=DEVICE_SERIAL,
+            running_mins=2,
+            maxStep=20
+        ),
+        configs_path = None  # Default, if your configs folder is located in the root directory, miss this.           
+    )
+    
+    # restart your driver session or clean instance here
+    # ...
+    
+    return  # this make your following steps of this testcase not work
 ```
 
+
+
 ## Test Reports（测试报告）
 
 Kea2 automatically generates a HTML test report after each testing session. You can find the report in `output/` under your working directory.
@@ -379,7 +413,7 @@ kea2做了什么：
 
 > Guided, Stochastic Model-Based GUI Testing of Android Apps. ESEC/FSE 2017.  [pdf](https://dl.acm.org/doi/10.1145/3106237.3106298)
 
-### Maintainers/Contributors
+## Maintainers/Contributors
 
 Kea2 has been actively developed and maintained by the people in [ecnusse](https://github.com/ecnusse):
 
@@ -397,7 +431,13 @@ Kea2 has been actively developed and maintained by the people in [ecnusse](https
 
 Kea2 has also received many valuable insights, advices, feedbacks and lessons shared by several industrial people from Bytedance ([Zhao Zhang](https://github.com/zhangzhao4444), Yuhui Su from the Fastbot team), OPay (Tiesong Liu), WeChat (Haochuan Lu, Yuetang Deng), Huawei, Xiaomi and etc. Kudos!
 
-### Star History
+### Become a Contributor!
+
+Kea2 is an open-source project and we are calling for more contributors to join us!
+
+See [Developer guide](DEVELOP.md) for more details.
+
+## Star History
 
 [![Star History Chart](https://api.star-history.com/svg?repos=ecnusse/Kea2&type=Date)](https://www.star-history.com/#ecnusse/Kea2&Date)
 

{kea2_python-1.0.2 → kea2_python-1.0.4}/Kea2_python.egg-info/SOURCES.txt

@@ -12,6 +12,7 @@ kea2/absDriver.py
 kea2/adbUtils.py
 kea2/cli.py
 kea2/fastbotManager.py
+kea2/kea2_api.py
 kea2/keaUtils.py
 kea2/kea_launcher.py
 kea2/logWatcher.py
@@ -46,4 +47,5 @@ kea2/report/report_merger.py
 kea2/report/utils.py
 kea2/report/templates/bug_report_template.html
 kea2/report/templates/merged_bug_report_template.html
-tests/test_u2Selector.py
+tests/test_u2Selector.py
+tests/test_xpath.py

{kea2_python-1.0.2 → kea2_python-1.0.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: Kea2-python
-Version: 1.0.2
+Version: 1.0.4
 Summary: A python library for supporting and customizing automated UI testing for mobile apps
 Author-email: Xixian Liang <xixian@stu.ecnu.edu.cn>
 Requires-Python: >=3.8
@@ -26,8 +26,11 @@ Dynamic: license-file
 
 Please contact Xixian Liang at [xixian@stu.ecnu.edu.cn](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.
 
-### Github repo link
-[https://github.com/ecnusse/Kea2](https://github.com/ecnusse/Kea2)
+####  Github repo [https://github.com/ecnusse/Kea2](https://github.com/ecnusse/Kea2)
+####  Gitee mirror [https://gitee.com/XixianLiang/Kea2](https://gitee.com/XixianLiang/Kea2)
+
+
+
 
 ### [点击此处：查看中文文档](README_cn.md) 
 
@@ -43,7 +46,7 @@ Please contact Xixian Liang at [xixian@stu.ecnu.edu.cn](xixian@stu.ecnu.edu.cn)
 
 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](https://github.com/bytedance/Fastbot_Android), *an industrial-strength automated UI testing tool*, and [uiautomator2](https://github.com/openatx/uiautomator2), *an easy-to-use and stable Android automation library*.
+Kea2 is currently built on top of [Fastbot](https://github.com/ecnusse/Fastbot_Android) 3.0 (a modified/enhanced version of the original [FastBot](https://github.com/bytedance/Fastbot_Android) 2.0), *an industrial-strength automated UI testing tool from ByteDance*, and [uiautomator2](https://github.com/openatx/uiautomator2), *an easy-to-use and stable Android automation library*. 
 Kea2 currently targets [Android](https://en.wikipedia.org/wiki/Android_(operating_system)) apps. 
 
 ## Novelty & Important features
@@ -90,7 +93,7 @@ Please let us know and willing to hear your feedback/questions if you are also u
 Kea2 currently works with:
 - [unittest](https://docs.python.org/3/library/unittest.html) as the testing framework to manage the scripts;
 - [uiautomator2](https://github.com/openatx/uiautomator2) as the UI test driver; 
-- [Fastbot](https://github.com/bytedance/Fastbot_Android) as the backend automated UI testing tool.
+- [Fastbot](https://github.com/bytedance/Fastbot_Android) as the backend automated UI testing tool. 
 
 In the future, Kea2 will be extended to support
 - [pytest](https://docs.pytest.org/en/stable/), another popular python testing framework;
@@ -208,7 +211,7 @@ You can find the full example in script `quicktest.py`, and run this script with
 
 ```bash
 # Launch Kea2 and load one single script quicktest.py.
-kea2 run -p it.feio.android.omninotes.alpha --agent u2 --running-minutes 10 --throttle 200 --driver-name d propertytest discover -p quicktest.py
+kea2 run -p it.feio.android.omninotes.alpha --running-minutes 10 --throttle 200 --driver-name d propertytest discover -p quicktest.py
 ```
 
 ## Feature 3(运行增强版Fastbot：加入自动断言)
@@ -243,7 +246,8 @@ For the preceding always-holding property, we can write the following script to
     )
     def test_input_box(self):
 
-        # genenerate a random non-empty string (this is also property-based testing by feeding random text inputs!)
+        # 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()
 
@@ -261,9 +265,7 @@ For the preceding always-holding property, we can write the following script to
 
 You can run this example by using the similar command line in Feature 2.
 
-## Feature 4 (Experimental feature, 实验中，脚本与遍历的混合测试)
-
-> This feature is still under development. We are looking forward to your feedback! Contact us if you're interested in this feature.
+## Feature 4(兼容已有脚本：通过前置脚本步骤到达特定层次)
 
 Kea2 supports reusing existing Ui test Scripts. We are inspired by the idea that: *The existing Ui test scripts usually cover important app functionalities and can reach deep app states. Thus, they can be used as good "guiding scripts" to drive Fastbot to explore important and deep app states.*
 
@@ -271,22 +273,54 @@ For example, you may already have some existing Ui test scripts "login and add a
 
 ### Example
 
-See [guide_scripts.py](guide_scripts.py) for a full example.
+Here are four example scripts in hybridetest_examples, each corresponding to different forms of user scripts, showing you how to launch kea2 in the existing code.
 
-By the decorator `@interruptable`, you can mark the testcase as "interruptable" so that Kea2 can recognize this script and launch fuzzing test after it returns. 
+Specifically:  
 
-Since the state of app is probably unpredicted after fuzzing tests, Kea2 provides a `common_teardown` function to clean up the environment between previous script and next script. The function can be manually specified in `configs/teardown.py`.
+* [u2_unittest_example.py](hybridtest_examples\u2_unittest_example.py) is a u2 script organized with unittest.
+* [u2_pytest_example.py](hybridtest_examples\u2_pytest_example.py) is a u2 script organized with pytest.
+* [appium_unittest_example.py](hybridtest_examples\appium_unittest_example.py) is an appium script organized with unittest.
+* [appium_pytest_example.py](hybridtest_examples\appium_pytest_example.py) is an appium script organized with pytest.
 
-You can find the full example in `guide_scripts.py`, `property_omninotes.py`  and `configs/teardown.py` .  You can run one of the following commands:
+Some notes:
 
-```bash
-# Guide with guide_scripts.py and launch fuzzing test after every script.
-kea2 run -p it.feio.android.omninotes.alpha --agent u2 --running-minutes 10 --throttle 500 --max-step 15 --driver-name d unittest discover -p guide_scripts.py 
+1. You can control whether to execute the kea2-related code you have written by modifying the condition of 'if'. This allows you to easily enable or disable kea2 operations in the same script. Here we use environment variable as an example.
+2. Since kea2 is driven by u2, if an appium-written script wants to launch kea2, it is necessary to first close the appium session. Remember to configure the parameter `"noReset": True` in `desired_caps` to avoid resetting the application when closing the session.
+3. You need to insert the following code template into your existing test cases: Here, you can add your own hook logic in the commented sections, including starting or stopping the appium session, cleaning up instances, etc. This depends on how you want to design the setup and teardown. Apart from that, you only need to configure the `option` parameter and `configs_path` parameter(where your directory `configs` located, btw, `configs`'s location dependon where you executed `kea2 init`), then pass it to the `run_kea2_testing` function.
 
-# Guide with guide_scripts.py and launch fuzzing test after every script(check properties during fuzzing).
-kea2 run -p it.feio.android.omninotes.alpha --agent u2 --running-minutes 10 --throttle 500 --max-step 15 --driver-name d unittest discover -p guide_scripts.py propertytest discover -p quickstart2.py
+```python
+from kea2 import Kea2Tester, Options, U2Driver
+
+if os.environ.get('KEA2_HYBRID_MODE', '').lower() == 'true': 
+    '''
+    Note: The if condition here can be modified as needed according to the actual 
+    situation of the project, the form of environment variables is just an example.    
+    '''
+
+    # close your driver session etc. here
+    # ...
+    
+    tester = Kea2Tester()
+    result = self.tester.run_kea2_testing(
+        Options(
+            driverName="d",
+            packageNames=[PACKAGE_NAME],
+            propertytest_args=["discover", "-p", "Omninotes_Sample.py"],
+            serial=DEVICE_SERIAL,
+            running_mins=2,
+            maxStep=20
+        ),
+        configs_path = None  # Default, if your configs folder is located in the root directory, miss this.           
+    )
+    
+    # restart your driver session or clean instance here
+    # ...
+    
+    return  # this make your following steps of this testcase not work
 ```
 
+
+
 ## Test Reports（测试报告）
 
 Kea2 automatically generates a HTML test report after each testing session. You can find the report in `output/` under your working directory.
@@ -379,7 +413,7 @@ kea2做了什么：
 
 > Guided, Stochastic Model-Based GUI Testing of Android Apps. ESEC/FSE 2017.  [pdf](https://dl.acm.org/doi/10.1145/3106237.3106298)
 
-### Maintainers/Contributors
+## Maintainers/Contributors
 
 Kea2 has been actively developed and maintained by the people in [ecnusse](https://github.com/ecnusse):
 
@@ -397,7 +431,13 @@ Kea2 has been actively developed and maintained by the people in [ecnusse](https
 
 Kea2 has also received many valuable insights, advices, feedbacks and lessons shared by several industrial people from Bytedance ([Zhao Zhang](https://github.com/zhangzhao4444), Yuhui Su from the Fastbot team), OPay (Tiesong Liu), WeChat (Haochuan Lu, Yuetang Deng), Huawei, Xiaomi and etc. Kudos!
 
-### Star History
+### Become a Contributor!
+
+Kea2 is an open-source project and we are calling for more contributors to join us!
+
+See [Developer guide](DEVELOP.md) for more details.
+
+## Star History
 
 [![Star History Chart](https://api.star-history.com/svg?repos=ecnusse/Kea2&type=Date)](https://www.star-history.com/#ecnusse/Kea2&Date)
 

{kea2_python-1.0.2 → kea2_python-1.0.4}/README.md

@@ -11,8 +11,11 @@
 
 Please contact Xixian Liang at [xixian@stu.ecnu.edu.cn](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.
 
-### Github repo link
-[https://github.com/ecnusse/Kea2](https://github.com/ecnusse/Kea2)
+####  Github repo [https://github.com/ecnusse/Kea2](https://github.com/ecnusse/Kea2)
+####  Gitee mirror [https://gitee.com/XixianLiang/Kea2](https://gitee.com/XixianLiang/Kea2)
+
+
+
 
 ### [点击此处：查看中文文档](README_cn.md) 
 
@@ -28,7 +31,7 @@ Please contact Xixian Liang at [xixian@stu.ecnu.edu.cn](xixian@stu.ecnu.edu.cn)
 
 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](https://github.com/bytedance/Fastbot_Android), *an industrial-strength automated UI testing tool*, and [uiautomator2](https://github.com/openatx/uiautomator2), *an easy-to-use and stable Android automation library*.
+Kea2 is currently built on top of [Fastbot](https://github.com/ecnusse/Fastbot_Android) 3.0 (a modified/enhanced version of the original [FastBot](https://github.com/bytedance/Fastbot_Android) 2.0), *an industrial-strength automated UI testing tool from ByteDance*, and [uiautomator2](https://github.com/openatx/uiautomator2), *an easy-to-use and stable Android automation library*. 
 Kea2 currently targets [Android](https://en.wikipedia.org/wiki/Android_(operating_system)) apps. 
 
 ## Novelty & Important features
@@ -75,7 +78,7 @@ Please let us know and willing to hear your feedback/questions if you are also u
 Kea2 currently works with:
 - [unittest](https://docs.python.org/3/library/unittest.html) as the testing framework to manage the scripts;
 - [uiautomator2](https://github.com/openatx/uiautomator2) as the UI test driver; 
-- [Fastbot](https://github.com/bytedance/Fastbot_Android) as the backend automated UI testing tool.
+- [Fastbot](https://github.com/bytedance/Fastbot_Android) as the backend automated UI testing tool. 
 
 In the future, Kea2 will be extended to support
 - [pytest](https://docs.pytest.org/en/stable/), another popular python testing framework;
@@ -193,7 +196,7 @@ You can find the full example in script `quicktest.py`, and run this script with
 
 ```bash
 # Launch Kea2 and load one single script quicktest.py.
-kea2 run -p it.feio.android.omninotes.alpha --agent u2 --running-minutes 10 --throttle 200 --driver-name d propertytest discover -p quicktest.py
+kea2 run -p it.feio.android.omninotes.alpha --running-minutes 10 --throttle 200 --driver-name d propertytest discover -p quicktest.py
 ```
 
 ## Feature 3(运行增强版Fastbot：加入自动断言)
@@ -228,7 +231,8 @@ For the preceding always-holding property, we can write the following script to
     )
     def test_input_box(self):
 
-        # genenerate a random non-empty string (this is also property-based testing by feeding random text inputs!)
+        # 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()
 
@@ -246,9 +250,7 @@ For the preceding always-holding property, we can write the following script to
 
 You can run this example by using the similar command line in Feature 2.
 
-## Feature 4 (Experimental feature, 实验中，脚本与遍历的混合测试)
-
-> This feature is still under development. We are looking forward to your feedback! Contact us if you're interested in this feature.
+## Feature 4(兼容已有脚本：通过前置脚本步骤到达特定层次)
 
 Kea2 supports reusing existing Ui test Scripts. We are inspired by the idea that: *The existing Ui test scripts usually cover important app functionalities and can reach deep app states. Thus, they can be used as good "guiding scripts" to drive Fastbot to explore important and deep app states.*
 
@@ -256,22 +258,54 @@ For example, you may already have some existing Ui test scripts "login and add a
 
 ### Example
 
-See [guide_scripts.py](guide_scripts.py) for a full example.
+Here are four example scripts in hybridetest_examples, each corresponding to different forms of user scripts, showing you how to launch kea2 in the existing code.
 
-By the decorator `@interruptable`, you can mark the testcase as "interruptable" so that Kea2 can recognize this script and launch fuzzing test after it returns. 
+Specifically:  
 
-Since the state of app is probably unpredicted after fuzzing tests, Kea2 provides a `common_teardown` function to clean up the environment between previous script and next script. The function can be manually specified in `configs/teardown.py`.
+* [u2_unittest_example.py](hybridtest_examples\u2_unittest_example.py) is a u2 script organized with unittest.
+* [u2_pytest_example.py](hybridtest_examples\u2_pytest_example.py) is a u2 script organized with pytest.
+* [appium_unittest_example.py](hybridtest_examples\appium_unittest_example.py) is an appium script organized with unittest.
+* [appium_pytest_example.py](hybridtest_examples\appium_pytest_example.py) is an appium script organized with pytest.
 
-You can find the full example in `guide_scripts.py`, `property_omninotes.py`  and `configs/teardown.py` .  You can run one of the following commands:
+Some notes:
 
-```bash
-# Guide with guide_scripts.py and launch fuzzing test after every script.
-kea2 run -p it.feio.android.omninotes.alpha --agent u2 --running-minutes 10 --throttle 500 --max-step 15 --driver-name d unittest discover -p guide_scripts.py 
+1. You can control whether to execute the kea2-related code you have written by modifying the condition of 'if'. This allows you to easily enable or disable kea2 operations in the same script. Here we use environment variable as an example.
+2. Since kea2 is driven by u2, if an appium-written script wants to launch kea2, it is necessary to first close the appium session. Remember to configure the parameter `"noReset": True` in `desired_caps` to avoid resetting the application when closing the session.
+3. You need to insert the following code template into your existing test cases: Here, you can add your own hook logic in the commented sections, including starting or stopping the appium session, cleaning up instances, etc. This depends on how you want to design the setup and teardown. Apart from that, you only need to configure the `option` parameter and `configs_path` parameter(where your directory `configs` located, btw, `configs`'s location dependon where you executed `kea2 init`), then pass it to the `run_kea2_testing` function.
 
-# Guide with guide_scripts.py and launch fuzzing test after every script(check properties during fuzzing).
-kea2 run -p it.feio.android.omninotes.alpha --agent u2 --running-minutes 10 --throttle 500 --max-step 15 --driver-name d unittest discover -p guide_scripts.py propertytest discover -p quickstart2.py
+```python
+from kea2 import Kea2Tester, Options, U2Driver
+
+if os.environ.get('KEA2_HYBRID_MODE', '').lower() == 'true': 
+    '''
+    Note: The if condition here can be modified as needed according to the actual 
+    situation of the project, the form of environment variables is just an example.    
+    '''
+
+    # close your driver session etc. here
+    # ...
+    
+    tester = Kea2Tester()
+    result = self.tester.run_kea2_testing(
+        Options(
+            driverName="d",
+            packageNames=[PACKAGE_NAME],
+            propertytest_args=["discover", "-p", "Omninotes_Sample.py"],
+            serial=DEVICE_SERIAL,
+            running_mins=2,
+            maxStep=20
+        ),
+        configs_path = None  # Default, if your configs folder is located in the root directory, miss this.           
+    )
+    
+    # restart your driver session or clean instance here
+    # ...
+    
+    return  # this make your following steps of this testcase not work
 ```
 
+
+
 ## Test Reports（测试报告）
 
 Kea2 automatically generates a HTML test report after each testing session. You can find the report in `output/` under your working directory.
@@ -364,7 +398,7 @@ kea2做了什么：
 
 > Guided, Stochastic Model-Based GUI Testing of Android Apps. ESEC/FSE 2017.  [pdf](https://dl.acm.org/doi/10.1145/3106237.3106298)
 
-### Maintainers/Contributors
+## Maintainers/Contributors
 
 Kea2 has been actively developed and maintained by the people in [ecnusse](https://github.com/ecnusse):
 
@@ -382,7 +416,13 @@ Kea2 has been actively developed and maintained by the people in [ecnusse](https
 
 Kea2 has also received many valuable insights, advices, feedbacks and lessons shared by several industrial people from Bytedance ([Zhao Zhang](https://github.com/zhangzhao4444), Yuhui Su from the Fastbot team), OPay (Tiesong Liu), WeChat (Haochuan Lu, Yuetang Deng), Huawei, Xiaomi and etc. Kudos!
 
-### Star History
+### Become a Contributor!
+
+Kea2 is an open-source project and we are calling for more contributors to join us!
+
+See [Developer guide](DEVELOP.md) for more details.
+
+## Star History
 
 [![Star History Chart](https://api.star-history.com/svg?repos=ecnusse/Kea2&type=Date)](https://www.star-history.com/#ecnusse/Kea2&Date)
 

kea2_python-1.0.4/kea2/__init__.py

@@ -0,0 +1,3 @@
+from .keaUtils import KeaTestRunner, precondition, prob, max_tries, Options, interruptable,HybridTestRunner,kea2_breakpoint
+from .kea2_api import Kea2Tester
+from .u2Driver import U2Driver

{kea2_python-1.0.2 → kea2_python-1.0.4}/kea2/cli.py

@@ -95,13 +95,12 @@ def cmd_merge(args):
         # Merge test reports
         merged_report = merger.merge_reports(args.paths, args.output)
 
-        # Print results
-        print(f"✅ Test reports merged successfully!", flush=True)
-        print(f"📊 Merged report: {merged_report}", flush=True)
-
-        # Get merge summary
-        merge_summary = merger.get_merge_summary()
-        print(f"📈 Merged {merge_summary.get('merged_directories', 0)} directories", flush=True)
+        if merged_report is not None:
+            print(f"✅ Test reports merged successfully!", flush=True)
+            print(f"📊 Merged report: {merged_report}", flush=True)
+            # Get merge summary
+            merge_summary = merger.get_merge_summary()
+            print(f"📈 Merged {merge_summary.get('merged_directories', 0)} directories", flush=True)
 
     except Exception as e:
         logger.error(f"Error during merge operation: {e}")      

{kea2_python-1.0.2 → kea2_python-1.0.4}/kea2/fastbotManager.py

@@ -41,62 +41,12 @@ class FastbotManager:
         :params: port: the listening port for script driver
         :return: the fastbot daemon thread
         """
-        cur_dir = Path(__file__).parent
-        self.dev.sync.push(
-            Path.joinpath(cur_dir, "assets/monkeyq.jar"),
-            "/sdcard/monkeyq.jar"
-        )
-        self.dev.sync.push(
-            Path.joinpath(cur_dir, "assets/fastbot-thirdpart.jar"),
-            "/sdcard/fastbot-thirdpart.jar",
-        )
-        self.dev.sync.push(
-            Path.joinpath(cur_dir, "assets/kea2-thirdpart.jar"),
-            "/sdcard/kea2-thirdpart.jar",
-        )
-        self.dev.sync.push(
-            Path.joinpath(cur_dir, "assets/framework.jar"),
-            "/sdcard/framework.jar",
-        )
-        self.dev.sync.push(
-            Path.joinpath(cur_dir, "assets/fastbot_libs/arm64-v8a/libfastbot_native.so"),
-            "/data/local/tmp/arm64-v8a/libfastbot_native.so",
-        )
-        self.dev.sync.push(
-            Path.joinpath(cur_dir, "assets/fastbot_libs/armeabi-v7a/libfastbot_native.so"),
-            "/data/local/tmp/armeabi-v7a/libfastbot_native.so",
-        )
-        self.dev.sync.push(
-            Path.joinpath(cur_dir, "assets/fastbot_libs/x86/libfastbot_native.so"),
-            "/data/local/tmp/x86/libfastbot_native.so",
-        )
-        self.dev.sync.push(
-            Path.joinpath(cur_dir, "assets/fastbot_libs/x86_64/libfastbot_native.so"),
-            "/data/local/tmp/x86_64/libfastbot_native.so",
-        )
-
-        cwd = getProjectRoot()
-        whitelist = self.options.act_whitelist_file
-        blacklist = self.options.act_blacklist_file
-        if bool(whitelist) ^ bool(blacklist):
-            if whitelist:
-                file_to_push = cwd / 'configs' / 'awl.strings'
-                remote_path = whitelist
-            else:
-                file_to_push = cwd / 'configs' / 'abl.strings'
-                remote_path = blacklist
-
-            self.dev.sync.push(
-                file_to_push,
-                remote_path
-            )
 
+        self._push_libs()
         t = self._startFastbotService()
         logger.info("Running Fastbot...")
-
         return t
 
-
     def check_alive(self):
         """
         check if the script driver and proxy server are alive.
@@ -183,6 +133,58 @@ class FastbotManager:
     @property
     def device_output_dir(self):
         return self._device_output_dir
+    
+    def _push_libs(self):
+        logger.info("Pushing Fastbot libraries to device...")
+        cur_dir = Path(__file__).parent
+        self.dev.sync.push(
+            Path.joinpath(cur_dir, "assets/monkeyq.jar"),
+            "/sdcard/monkeyq.jar"
+        )
+        self.dev.sync.push(
+            Path.joinpath(cur_dir, "assets/fastbot-thirdpart.jar"),
+            "/sdcard/fastbot-thirdpart.jar",
+        )
+        self.dev.sync.push(
+            Path.joinpath(cur_dir, "assets/kea2-thirdpart.jar"),
+            "/sdcard/kea2-thirdpart.jar",
+        )
+        self.dev.sync.push(
+            Path.joinpath(cur_dir, "assets/framework.jar"),
+            "/sdcard/framework.jar",
+        )
+        self.dev.sync.push(
+            Path.joinpath(cur_dir, "assets/fastbot_libs/arm64-v8a/libfastbot_native.so"),
+            "/data/local/tmp/arm64-v8a/libfastbot_native.so",
+        )
+        self.dev.sync.push(
+            Path.joinpath(cur_dir, "assets/fastbot_libs/armeabi-v7a/libfastbot_native.so"),
+            "/data/local/tmp/armeabi-v7a/libfastbot_native.so",
+        )
+        self.dev.sync.push(
+            Path.joinpath(cur_dir, "assets/fastbot_libs/x86/libfastbot_native.so"),
+            "/data/local/tmp/x86/libfastbot_native.so",
+        )
+        self.dev.sync.push(
+            Path.joinpath(cur_dir, "assets/fastbot_libs/x86_64/libfastbot_native.so"),
+            "/data/local/tmp/x86_64/libfastbot_native.so",
+        )
+
+        cwd = getProjectRoot()
+        whitelist = self.options.act_whitelist_file
+        blacklist = self.options.act_blacklist_file
+        if bool(whitelist) ^ bool(blacklist):
+            if whitelist:
+                file_to_push = cwd / 'configs' / 'awl.strings'
+                remote_path = whitelist
+            else:
+                file_to_push = cwd / 'configs' / 'abl.strings'
+                remote_path = blacklist
+
+            self.dev.sync.push(
+                file_to_push,
+                remote_path
+            )
 
     def _startFastbotService(self) -> ADBStreamShell_V2:
         shell_command = [