Kea2-python 0.0.1b1__tar.gz → 0.0.1b3__tar.gz

{kea2_python-0.0.1b1 → kea2_python-0.0.1b3}/Kea2_python.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: Kea2-python
-Version: 0.0.1b1
+Version: 0.0.1b3
 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
@@ -20,7 +20,7 @@ Dynamic: license-file
     <img src="https://github.com/user-attachments/assets/58f68b00-cc9c-4620-9e2e-66c43cf7caae" style="border-radius: 14px; width: 20%; height: 20%;"/> 
 </div>
 
-Kea2 is an easy-to-use Python library for supporting, customizing and improving automated UI testing for mobile apps. The library is currently built on top of [Fastbot](https://github.com/bytedance/Fastbot_Android) and [uiautomator2](https://github.com/openatx/uiautomator2), and targeting [Android](https://en.wikipedia.org/wiki/Android_(operating_system)) apps.
+Kea2 is an easy-to-use Python library for supporting, customizing and improving automated UI testing for mobile apps. Kea2's novelty is able to fuse the scripts (usually written by human) with automated UI testing tools, thus allowing many interesting and powerful features. Kea2 is currently built on top of [Fastbot](https://github.com/bytedance/Fastbot_Android) and [uiautomator2](https://github.com/openatx/uiautomator2) and targets [Android](https://en.wikipedia.org/wiki/Android_(operating_system)) apps.
 
 ### Kea2 has three important features:
 - **Feature 1**(查找稳定性问题): coming with the full capability of [Fastbot](https://github.com/bytedance/Fastbot_Android) for stress testing and finding *stability problems* (i.e., *crashing bugs*); 
@@ -49,7 +49,7 @@ Kea2, released as a Python library, currently works with:
 - [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.
 
-In the future, Kea2 will be extended to support
+**Roadmap**: In the future, Kea2 will be extended to support
 - [pytest](https://docs.pytest.org/en/stable/)
 - [Appium](https://github.com/appium/appium), [Hypium]() (for HarmonyOS)
 - other automated UI testing tools (not limited to Fastbot)
@@ -61,13 +61,14 @@ In the future, Kea2 will be extended to support
 Running requirements/environment:
 - support Windows, MacOS and Linux
 - python 3.8+
+- Android 4.4+
 - Android SDK installed
 - **VPN closed** (Features 2 and 3 required)
 
 
 Install Kea2 by `pip`:
 ```bash
-python3 -m pip install Kea2-python
+python3 -m pip install kea2-python
 ```
 
 Find Kea2's additional options by running 
@@ -174,20 +175,31 @@ You can find the full example in script `quicktest.py`, and run this script with
 kea2 run -s "emulator-5554" -p it.feio.android.omninotes.alpha --agent u2 --running-minutes 10 --throttle 200 --driver-name d unittest discover -p quicktest.py
 ```
 
-### Example 2: blacklisting specific UI widgets
+### Example 2: blacklisting specific UI elements
 
-We support blacklisting specific widgets so that Fastbot can avoid interacting with these widgets during fuzzing. We support (1) `Global Block List` (always taking effective), and (2) `Conditional Block List` (only taking effective when some conditions are met).
+We support blacklisting specific elements so that Fastbot can avoid interacting with these 
+elements during fuzzing. 
 
-The list of blocked widgets are specified in Kea2's config file `configs/widget.block.py` (generated when running `kea2 init`). 
-The widgets needed to be blocked can be flexibly specified by u2 selector (e.g., `text`, `description`) or `xpath`, etc.
+We support two granularity levels for UI blocking:
 
-#### Global Block List
+- Widget Blocking: Block individual UI widgets.
+
+- Tree Blocking : Block a UI widget trees by specifying its root node.
+It can block the root node and all its descendants.
+
+We support (1) `Global Block List` (always taking effective), and (2) `Conditional Block List` (only taking effective when some conditions are met).
+
+The list of blocked elements are specified in Kea2's config file `configs/widget.block.py` (generated when running `kea2 init`). 
+The elements needed to be blocked can be flexibly specified by u2 selector (e.g., `text`, `description`) or `xpath`, etc.
+
+#### Widget Blocking
+##### Global Block List
 We can define the function `global_block_widgets` to specify which UI widgets should be blocked globally. The blocking always takes effect. 
 
 ```python
 # file: configs/widget.block.py
 
-    def global_block_widgets(d: "Device"):
+def global_block_widgets(d: "Device"):
     """
     global block list.
     return the widgets which should be blocked globally
@@ -196,8 +208,8 @@ We can define the function `global_block_widgets` to specify which UI widgets sh
             d.xpath(".//node[@text='widget to block']"),
             d(description="widgets to block")]
 ```
-#### Conditional Block List
-We can define any reserved function whose name starts with "block_" and decorate such function by `@precondition` to allow conditional block list.
+##### Conditional Block List
+We can define any reserved function whose name starts with "block_" (but not requiring "block_tree_" prefix) and decorate such function by `@precondition` to allow conditional block list.
 In this case, the blocking only takes effect when the precondition is satisfied.
 ```python
 # file: configs/widget.block.py
@@ -211,6 +223,37 @@ def block_sth(d: "Device"):
             d(description="widgets to block")]
 ```
 
+#### Tree Blocking
+##### Global Block List
+We can define the function `global_block_tree` to specify which UI widget trees should be blocked globally. The blocking always takes effect. 
+
+```python
+# file: configs/widget.block.py
+
+def global_block_tree(d: "Device"):
+    """
+    Specify UI widget trees to be blocked globally during testing.
+    Returns a list of root nodes whose entire subtrees will be blocked from exploration.
+    This function is only available in 'u2 agent' mode.
+    """
+     return [d(text="trees to block"), d.xpath(".//node[@text='tree to block']")]
+```
+##### Conditional Block List
+We can define any reserved function whose name starts with "block_tree_" and decorate such function by `@precondition` to allow conditional block list.
+In this case, the blocking only takes effect when the precondition is satisfied.
+```python
+# file: configs/widget.block.py
+
+# Example of conditional tree blocking with precondition
+
+@precondition(lambda d: d(text="In the home page").exists)
+def block_tree_sth(d: "Device"):
+    # Note: Function name must start with "block_tree_"
+    return [d(text="trees to block"), 
+            d.xpath(".//node[@text='tree to block']"),
+            d(description="trees to block")]
+```
+
 ## Feature 3(支持断言机制): Supporting auto-assertions by scripts.
 
 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. This idea is inspired by  [property-based testing](https://en.wikipedia.org/wiki/Software_testing#Property_testing) inheritted from [Kea](https://github.com/ecnusse/Kea).
@@ -304,31 +347,6 @@ class MyFirstTest(unittest.TestCase):
 
 You can read [Kea - Write your fisrt property](https://kea-docs.readthedocs.io/en/latest/part-keaUserManuel/first_property.html) for more details.
 
-### Notes
-Currently, in `@precondition` decorator and `widgets.block.py`. We only support basic selector (No parent-child relationship) in uiautomator2. The Script body in the function fully support uiautomator2.
-
-| | **Support** | **Not support** |
-| -- | -- | -- |
-| **Selctor** | `d(text="1").exist` | `d(text="1").child(text="2").exist` |
-
-If you need to specify `parent-child` relation ship in `@precondition`, specify it in xpath.
-
-for example: 
-
-```python
-# Do not use:
-# @precondition(lambda self: 
-#      self.d(className="android.widget.ListView").child(text="Bluetooth")
-# ):
-# ...
-
-# Use
-@precondition(lambda self: 
-    self.d.xpath('//android.widget.ListView/*[@text="Bluetooth"]')
-):
-...
-```
-
 
 ## Launching Kea2
 
@@ -353,16 +371,17 @@ kea2 run -s "emulator-5554" -p it.feio.android.omninotes.alpha --agent u2 --runn
 kea2 run -s "emulator-5554" -p it.feio.android.omninotes.alpha --agent u2 --running-minutes 10 --throttle 200 --driver-name d unittest discover -s mytests/omni_notes
 ```
 
-| arg | meaning |
-| --- | --- |
-| -s | The serial of your device, which can be found by `adb devices` |
-| -p | The tested app's package name (e.g., com.example.app) | 
-| -o | The ouput directory for logs and results |
-| --agent |  {native, u2}. By default, `u2` is used and supports all the three important features of Kea2. If you hope to run the orignal Fastbot, please use `native`.|
-| --running-minutes | The time (m) to run Kea2 | 
-| --max-step | The maxium number of monkey events to send (only available in `--agent u2`) | 
-| --throttle | The delay time (ms) between two monkey events |
+| arg | meaning | default | 
+| --- | --- | --- |
+| -s | The serial of your device, which can be found by `adb devices` | |
+| -p | *The tested app's package name (e.g., com.example.app) | 
+| -o | The ouput directory for logs and results | `output` |
+| --agent |  {native, u2}. By default, `u2` is used and supports all the three important features of Kea2. If you hope to run the orignal Fastbot, please use `native`.| `u2` |
+| --running-minutes | The time (m) to run Kea2 | `10` |
+| --max-step | The maxium number of monkey events to send (only available in `--agent u2`) | `inf` |
+| --throttle | The delay time (ms) between two monkey events | `200` |
 | --driver-name | The name of driver used in the script. If `--driver-name d` is specified, you should use `d` to interact with a device, e..g, `self.d(..).click()`. |
+| --log-stamp | the stamp for log file and result file. (e.g. `--log-stamp 123` then `fastbot_123.log` and `result_123.json` will be generated.) default: current time stamp | |
 | unittest | Specify to load which scripts. This  sub-command `unittest` is fully compatible with unittest. See `python3 -m unittest -h` for more options of unittest. This option is only available in `--agent u2`.
 
 
@@ -425,6 +444,8 @@ running_mins: int = 10
 throttle: int = 200
 # the output_dir for saving logs and results
 output_dir: str = "output"
+# the stamp for log file and result file, default: current time stamp
+log_stamp: str = None
 ```
 
 ## Examining the running statistics of scripts .
@@ -469,6 +490,17 @@ Kea2 has been actively developed and maintained by the people in [ecnusse](https
 - [uiautomator2](https://github.com/openatx/uiautomator2)
 - [hypothesis](https://github.com/HypothesisWorks/hypothesis)
 
+### Relevant papers of Kea2
+
+> General and Practical Property-based Testing for Android Apps. ASE 2024. [pdf](https://dl.acm.org/doi/10.1145/3691620.3694986)
+
+> An Empirical Study of Functional Bugs in Android Apps. ISSTA 2023. [pdf](https://dl.acm.org/doi/10.1145/3597926.3598138)
+
+> Fastbot2: Reusable Automated Model-based GUI Testing for Android Enhanced by Reinforcement Learning. ASE 2022. [pdf](https://dl.acm.org/doi/10.1145/3551349.3559505)
+
+> Guided, Stochastic Model-Based GUI Testing of Android Apps. ESEC/FSE 2017.  [pdf](https://dl.acm.org/doi/10.1145/3106237.3106298)
+
+
 [^1]: 不少UI自动化测试工具提供了“自定义事件序列”能力（如[Fastbot](https://github.com/bytedance/Fastbot_Android/blob/main/handbook-cn.md#%E8%87%AA%E5%AE%9A%E4%B9%89%E4%BA%8B%E4%BB%B6%E5%BA%8F%E5%88%97) 和[AppCrawler](https://github.com/seveniruby/AppCrawler)），但在实际使用中存在不少问题，如自定义能力有限、使用不灵活等。此前不少Fastbot用户抱怨过其“自定义事件序列”在使用中的问题，如[#209](https://github.com/bytedance/Fastbot_Android/issues/209), [#225](https://github.com/bytedance/Fastbot_Android/issues/225), [#286](https://github.com/bytedance/Fastbot_Android/issues/286)等。
 
 [^2]: 在UI自动化测试过程中支持自动断言是一个很重要的能力，但几乎没有测试工具提供这样的能力。我们注意到[AppCrawler](https://ceshiren.com/t/topic/15801/5)的开发者曾经希望提供一种断言机制，得到了用户的热切响应，不少用户从21年就开始催更，但始终未能实现。

{kea2_python-0.0.1b1 → kea2_python-0.0.1b3}/Kea2_python.egg-info/SOURCES.txt

@@ -21,7 +21,6 @@ kea2/assets/framework.jar
 kea2/assets/monkeyq.jar
 kea2/assets/quicktest.py
 kea2/assets/u2.jar
-kea2/assets/fastbot_configs/ADBKeyBoard.apk
 kea2/assets/fastbot_configs/abl.strings
 kea2/assets/fastbot_configs/awl.strings
 kea2/assets/fastbot_configs/max.config

{kea2_python-0.0.1b1 → kea2_python-0.0.1b3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: Kea2-python
-Version: 0.0.1b1
+Version: 0.0.1b3
 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
@@ -20,7 +20,7 @@ Dynamic: license-file
     <img src="https://github.com/user-attachments/assets/58f68b00-cc9c-4620-9e2e-66c43cf7caae" style="border-radius: 14px; width: 20%; height: 20%;"/> 
 </div>
 
-Kea2 is an easy-to-use Python library for supporting, customizing and improving automated UI testing for mobile apps. The library is currently built on top of [Fastbot](https://github.com/bytedance/Fastbot_Android) and [uiautomator2](https://github.com/openatx/uiautomator2), and targeting [Android](https://en.wikipedia.org/wiki/Android_(operating_system)) apps.
+Kea2 is an easy-to-use Python library for supporting, customizing and improving automated UI testing for mobile apps. Kea2's novelty is able to fuse the scripts (usually written by human) with automated UI testing tools, thus allowing many interesting and powerful features. Kea2 is currently built on top of [Fastbot](https://github.com/bytedance/Fastbot_Android) and [uiautomator2](https://github.com/openatx/uiautomator2) and targets [Android](https://en.wikipedia.org/wiki/Android_(operating_system)) apps.
 
 ### Kea2 has three important features:
 - **Feature 1**(查找稳定性问题): coming with the full capability of [Fastbot](https://github.com/bytedance/Fastbot_Android) for stress testing and finding *stability problems* (i.e., *crashing bugs*); 
@@ -49,7 +49,7 @@ Kea2, released as a Python library, currently works with:
 - [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.
 
-In the future, Kea2 will be extended to support
+**Roadmap**: In the future, Kea2 will be extended to support
 - [pytest](https://docs.pytest.org/en/stable/)
 - [Appium](https://github.com/appium/appium), [Hypium]() (for HarmonyOS)
 - other automated UI testing tools (not limited to Fastbot)
@@ -61,13 +61,14 @@ In the future, Kea2 will be extended to support
 Running requirements/environment:
 - support Windows, MacOS and Linux
 - python 3.8+
+- Android 4.4+
 - Android SDK installed
 - **VPN closed** (Features 2 and 3 required)
 
 
 Install Kea2 by `pip`:
 ```bash
-python3 -m pip install Kea2-python
+python3 -m pip install kea2-python
 ```
 
 Find Kea2's additional options by running 
@@ -174,20 +175,31 @@ You can find the full example in script `quicktest.py`, and run this script with
 kea2 run -s "emulator-5554" -p it.feio.android.omninotes.alpha --agent u2 --running-minutes 10 --throttle 200 --driver-name d unittest discover -p quicktest.py
 ```
 
-### Example 2: blacklisting specific UI widgets
+### Example 2: blacklisting specific UI elements
 
-We support blacklisting specific widgets so that Fastbot can avoid interacting with these widgets during fuzzing. We support (1) `Global Block List` (always taking effective), and (2) `Conditional Block List` (only taking effective when some conditions are met).
+We support blacklisting specific elements so that Fastbot can avoid interacting with these 
+elements during fuzzing. 
 
-The list of blocked widgets are specified in Kea2's config file `configs/widget.block.py` (generated when running `kea2 init`). 
-The widgets needed to be blocked can be flexibly specified by u2 selector (e.g., `text`, `description`) or `xpath`, etc.
+We support two granularity levels for UI blocking:
 
-#### Global Block List
+- Widget Blocking: Block individual UI widgets.
+
+- Tree Blocking : Block a UI widget trees by specifying its root node.
+It can block the root node and all its descendants.
+
+We support (1) `Global Block List` (always taking effective), and (2) `Conditional Block List` (only taking effective when some conditions are met).
+
+The list of blocked elements are specified in Kea2's config file `configs/widget.block.py` (generated when running `kea2 init`). 
+The elements needed to be blocked can be flexibly specified by u2 selector (e.g., `text`, `description`) or `xpath`, etc.
+
+#### Widget Blocking
+##### Global Block List
 We can define the function `global_block_widgets` to specify which UI widgets should be blocked globally. The blocking always takes effect. 
 
 ```python
 # file: configs/widget.block.py
 
-    def global_block_widgets(d: "Device"):
+def global_block_widgets(d: "Device"):
     """
     global block list.
     return the widgets which should be blocked globally
@@ -196,8 +208,8 @@ We can define the function `global_block_widgets` to specify which UI widgets sh
             d.xpath(".//node[@text='widget to block']"),
             d(description="widgets to block")]
 ```
-#### Conditional Block List
-We can define any reserved function whose name starts with "block_" and decorate such function by `@precondition` to allow conditional block list.
+##### Conditional Block List
+We can define any reserved function whose name starts with "block_" (but not requiring "block_tree_" prefix) and decorate such function by `@precondition` to allow conditional block list.
 In this case, the blocking only takes effect when the precondition is satisfied.
 ```python
 # file: configs/widget.block.py
@@ -211,6 +223,37 @@ def block_sth(d: "Device"):
             d(description="widgets to block")]
 ```
 
+#### Tree Blocking
+##### Global Block List
+We can define the function `global_block_tree` to specify which UI widget trees should be blocked globally. The blocking always takes effect. 
+
+```python
+# file: configs/widget.block.py
+
+def global_block_tree(d: "Device"):
+    """
+    Specify UI widget trees to be blocked globally during testing.
+    Returns a list of root nodes whose entire subtrees will be blocked from exploration.
+    This function is only available in 'u2 agent' mode.
+    """
+     return [d(text="trees to block"), d.xpath(".//node[@text='tree to block']")]
+```
+##### Conditional Block List
+We can define any reserved function whose name starts with "block_tree_" and decorate such function by `@precondition` to allow conditional block list.
+In this case, the blocking only takes effect when the precondition is satisfied.
+```python
+# file: configs/widget.block.py
+
+# Example of conditional tree blocking with precondition
+
+@precondition(lambda d: d(text="In the home page").exists)
+def block_tree_sth(d: "Device"):
+    # Note: Function name must start with "block_tree_"
+    return [d(text="trees to block"), 
+            d.xpath(".//node[@text='tree to block']"),
+            d(description="trees to block")]
+```
+
 ## Feature 3(支持断言机制): Supporting auto-assertions by scripts.
 
 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. This idea is inspired by  [property-based testing](https://en.wikipedia.org/wiki/Software_testing#Property_testing) inheritted from [Kea](https://github.com/ecnusse/Kea).
@@ -304,31 +347,6 @@ class MyFirstTest(unittest.TestCase):
 
 You can read [Kea - Write your fisrt property](https://kea-docs.readthedocs.io/en/latest/part-keaUserManuel/first_property.html) for more details.
 
-### Notes
-Currently, in `@precondition` decorator and `widgets.block.py`. We only support basic selector (No parent-child relationship) in uiautomator2. The Script body in the function fully support uiautomator2.
-
-| | **Support** | **Not support** |
-| -- | -- | -- |
-| **Selctor** | `d(text="1").exist` | `d(text="1").child(text="2").exist` |
-
-If you need to specify `parent-child` relation ship in `@precondition`, specify it in xpath.
-
-for example: 
-
-```python
-# Do not use:
-# @precondition(lambda self: 
-#      self.d(className="android.widget.ListView").child(text="Bluetooth")
-# ):
-# ...
-
-# Use
-@precondition(lambda self: 
-    self.d.xpath('//android.widget.ListView/*[@text="Bluetooth"]')
-):
-...
-```
-
 
 ## Launching Kea2
 
@@ -353,16 +371,17 @@ kea2 run -s "emulator-5554" -p it.feio.android.omninotes.alpha --agent u2 --runn
 kea2 run -s "emulator-5554" -p it.feio.android.omninotes.alpha --agent u2 --running-minutes 10 --throttle 200 --driver-name d unittest discover -s mytests/omni_notes
 ```
 
-| arg | meaning |
-| --- | --- |
-| -s | The serial of your device, which can be found by `adb devices` |
-| -p | The tested app's package name (e.g., com.example.app) | 
-| -o | The ouput directory for logs and results |
-| --agent |  {native, u2}. By default, `u2` is used and supports all the three important features of Kea2. If you hope to run the orignal Fastbot, please use `native`.|
-| --running-minutes | The time (m) to run Kea2 | 
-| --max-step | The maxium number of monkey events to send (only available in `--agent u2`) | 
-| --throttle | The delay time (ms) between two monkey events |
+| arg | meaning | default | 
+| --- | --- | --- |
+| -s | The serial of your device, which can be found by `adb devices` | |
+| -p | *The tested app's package name (e.g., com.example.app) | 
+| -o | The ouput directory for logs and results | `output` |
+| --agent |  {native, u2}. By default, `u2` is used and supports all the three important features of Kea2. If you hope to run the orignal Fastbot, please use `native`.| `u2` |
+| --running-minutes | The time (m) to run Kea2 | `10` |
+| --max-step | The maxium number of monkey events to send (only available in `--agent u2`) | `inf` |
+| --throttle | The delay time (ms) between two monkey events | `200` |
 | --driver-name | The name of driver used in the script. If `--driver-name d` is specified, you should use `d` to interact with a device, e..g, `self.d(..).click()`. |
+| --log-stamp | the stamp for log file and result file. (e.g. `--log-stamp 123` then `fastbot_123.log` and `result_123.json` will be generated.) default: current time stamp | |
 | unittest | Specify to load which scripts. This  sub-command `unittest` is fully compatible with unittest. See `python3 -m unittest -h` for more options of unittest. This option is only available in `--agent u2`.
 
 
@@ -425,6 +444,8 @@ running_mins: int = 10
 throttle: int = 200
 # the output_dir for saving logs and results
 output_dir: str = "output"
+# the stamp for log file and result file, default: current time stamp
+log_stamp: str = None
 ```
 
 ## Examining the running statistics of scripts .
@@ -469,6 +490,17 @@ Kea2 has been actively developed and maintained by the people in [ecnusse](https
 - [uiautomator2](https://github.com/openatx/uiautomator2)
 - [hypothesis](https://github.com/HypothesisWorks/hypothesis)
 
+### Relevant papers of Kea2
+
+> General and Practical Property-based Testing for Android Apps. ASE 2024. [pdf](https://dl.acm.org/doi/10.1145/3691620.3694986)
+
+> An Empirical Study of Functional Bugs in Android Apps. ISSTA 2023. [pdf](https://dl.acm.org/doi/10.1145/3597926.3598138)
+
+> Fastbot2: Reusable Automated Model-based GUI Testing for Android Enhanced by Reinforcement Learning. ASE 2022. [pdf](https://dl.acm.org/doi/10.1145/3551349.3559505)
+
+> Guided, Stochastic Model-Based GUI Testing of Android Apps. ESEC/FSE 2017.  [pdf](https://dl.acm.org/doi/10.1145/3106237.3106298)
+
+
 [^1]: 不少UI自动化测试工具提供了“自定义事件序列”能力（如[Fastbot](https://github.com/bytedance/Fastbot_Android/blob/main/handbook-cn.md#%E8%87%AA%E5%AE%9A%E4%B9%89%E4%BA%8B%E4%BB%B6%E5%BA%8F%E5%88%97) 和[AppCrawler](https://github.com/seveniruby/AppCrawler)），但在实际使用中存在不少问题，如自定义能力有限、使用不灵活等。此前不少Fastbot用户抱怨过其“自定义事件序列”在使用中的问题，如[#209](https://github.com/bytedance/Fastbot_Android/issues/209), [#225](https://github.com/bytedance/Fastbot_Android/issues/225), [#286](https://github.com/bytedance/Fastbot_Android/issues/286)等。
 
 [^2]: 在UI自动化测试过程中支持自动断言是一个很重要的能力，但几乎没有测试工具提供这样的能力。我们注意到[AppCrawler](https://ceshiren.com/t/topic/15801/5)的开发者曾经希望提供一种断言机制，得到了用户的热切响应，不少用户从21年就开始催更，但始终未能实现。

{kea2_python-0.0.1b1 → kea2_python-0.0.1b3}/README.md

@@ -8,7 +8,7 @@
     <img src="https://github.com/user-attachments/assets/58f68b00-cc9c-4620-9e2e-66c43cf7caae" style="border-radius: 14px; width: 20%; height: 20%;"/> 
 </div>
 
-Kea2 is an easy-to-use Python library for supporting, customizing and improving automated UI testing for mobile apps. The library is currently built on top of [Fastbot](https://github.com/bytedance/Fastbot_Android) and [uiautomator2](https://github.com/openatx/uiautomator2), and targeting [Android](https://en.wikipedia.org/wiki/Android_(operating_system)) apps.
+Kea2 is an easy-to-use Python library for supporting, customizing and improving automated UI testing for mobile apps. Kea2's novelty is able to fuse the scripts (usually written by human) with automated UI testing tools, thus allowing many interesting and powerful features. Kea2 is currently built on top of [Fastbot](https://github.com/bytedance/Fastbot_Android) and [uiautomator2](https://github.com/openatx/uiautomator2) and targets [Android](https://en.wikipedia.org/wiki/Android_(operating_system)) apps.
 
 ### Kea2 has three important features:
 - **Feature 1**(查找稳定性问题): coming with the full capability of [Fastbot](https://github.com/bytedance/Fastbot_Android) for stress testing and finding *stability problems* (i.e., *crashing bugs*); 
@@ -37,7 +37,7 @@ Kea2, released as a Python library, currently works with:
 - [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.
 
-In the future, Kea2 will be extended to support
+**Roadmap**: In the future, Kea2 will be extended to support
 - [pytest](https://docs.pytest.org/en/stable/)
 - [Appium](https://github.com/appium/appium), [Hypium]() (for HarmonyOS)
 - other automated UI testing tools (not limited to Fastbot)
@@ -49,13 +49,14 @@ In the future, Kea2 will be extended to support
 Running requirements/environment:
 - support Windows, MacOS and Linux
 - python 3.8+
+- Android 4.4+
 - Android SDK installed
 - **VPN closed** (Features 2 and 3 required)
 
 
 Install Kea2 by `pip`:
 ```bash
-python3 -m pip install Kea2-python
+python3 -m pip install kea2-python
 ```
 
 Find Kea2's additional options by running 
@@ -162,20 +163,31 @@ You can find the full example in script `quicktest.py`, and run this script with
 kea2 run -s "emulator-5554" -p it.feio.android.omninotes.alpha --agent u2 --running-minutes 10 --throttle 200 --driver-name d unittest discover -p quicktest.py
 ```
 
-### Example 2: blacklisting specific UI widgets
+### Example 2: blacklisting specific UI elements
 
-We support blacklisting specific widgets so that Fastbot can avoid interacting with these widgets during fuzzing. We support (1) `Global Block List` (always taking effective), and (2) `Conditional Block List` (only taking effective when some conditions are met).
+We support blacklisting specific elements so that Fastbot can avoid interacting with these 
+elements during fuzzing. 
 
-The list of blocked widgets are specified in Kea2's config file `configs/widget.block.py` (generated when running `kea2 init`). 
-The widgets needed to be blocked can be flexibly specified by u2 selector (e.g., `text`, `description`) or `xpath`, etc.
+We support two granularity levels for UI blocking:
 
-#### Global Block List
+- Widget Blocking: Block individual UI widgets.
+
+- Tree Blocking : Block a UI widget trees by specifying its root node.
+It can block the root node and all its descendants.
+
+We support (1) `Global Block List` (always taking effective), and (2) `Conditional Block List` (only taking effective when some conditions are met).
+
+The list of blocked elements are specified in Kea2's config file `configs/widget.block.py` (generated when running `kea2 init`). 
+The elements needed to be blocked can be flexibly specified by u2 selector (e.g., `text`, `description`) or `xpath`, etc.
+
+#### Widget Blocking
+##### Global Block List
 We can define the function `global_block_widgets` to specify which UI widgets should be blocked globally. The blocking always takes effect. 
 
 ```python
 # file: configs/widget.block.py
 
-    def global_block_widgets(d: "Device"):
+def global_block_widgets(d: "Device"):
     """
     global block list.
     return the widgets which should be blocked globally
@@ -184,8 +196,8 @@ We can define the function `global_block_widgets` to specify which UI widgets sh
             d.xpath(".//node[@text='widget to block']"),
             d(description="widgets to block")]
 ```
-#### Conditional Block List
-We can define any reserved function whose name starts with "block_" and decorate such function by `@precondition` to allow conditional block list.
+##### Conditional Block List
+We can define any reserved function whose name starts with "block_" (but not requiring "block_tree_" prefix) and decorate such function by `@precondition` to allow conditional block list.
 In this case, the blocking only takes effect when the precondition is satisfied.
 ```python
 # file: configs/widget.block.py
@@ -199,6 +211,37 @@ def block_sth(d: "Device"):
             d(description="widgets to block")]
 ```
 
+#### Tree Blocking
+##### Global Block List
+We can define the function `global_block_tree` to specify which UI widget trees should be blocked globally. The blocking always takes effect. 
+
+```python
+# file: configs/widget.block.py
+
+def global_block_tree(d: "Device"):
+    """
+    Specify UI widget trees to be blocked globally during testing.
+    Returns a list of root nodes whose entire subtrees will be blocked from exploration.
+    This function is only available in 'u2 agent' mode.
+    """
+     return [d(text="trees to block"), d.xpath(".//node[@text='tree to block']")]
+```
+##### Conditional Block List
+We can define any reserved function whose name starts with "block_tree_" and decorate such function by `@precondition` to allow conditional block list.
+In this case, the blocking only takes effect when the precondition is satisfied.
+```python
+# file: configs/widget.block.py
+
+# Example of conditional tree blocking with precondition
+
+@precondition(lambda d: d(text="In the home page").exists)
+def block_tree_sth(d: "Device"):
+    # Note: Function name must start with "block_tree_"
+    return [d(text="trees to block"), 
+            d.xpath(".//node[@text='tree to block']"),
+            d(description="trees to block")]
+```
+
 ## Feature 3(支持断言机制): Supporting auto-assertions by scripts.
 
 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. This idea is inspired by  [property-based testing](https://en.wikipedia.org/wiki/Software_testing#Property_testing) inheritted from [Kea](https://github.com/ecnusse/Kea).
@@ -292,31 +335,6 @@ class MyFirstTest(unittest.TestCase):
 
 You can read [Kea - Write your fisrt property](https://kea-docs.readthedocs.io/en/latest/part-keaUserManuel/first_property.html) for more details.
 
-### Notes
-Currently, in `@precondition` decorator and `widgets.block.py`. We only support basic selector (No parent-child relationship) in uiautomator2. The Script body in the function fully support uiautomator2.
-
-| | **Support** | **Not support** |
-| -- | -- | -- |
-| **Selctor** | `d(text="1").exist` | `d(text="1").child(text="2").exist` |
-
-If you need to specify `parent-child` relation ship in `@precondition`, specify it in xpath.
-
-for example: 
-
-```python
-# Do not use:
-# @precondition(lambda self: 
-#      self.d(className="android.widget.ListView").child(text="Bluetooth")
-# ):
-# ...
-
-# Use
-@precondition(lambda self: 
-    self.d.xpath('//android.widget.ListView/*[@text="Bluetooth"]')
-):
-...
-```
-
 
 ## Launching Kea2
 
@@ -341,16 +359,17 @@ kea2 run -s "emulator-5554" -p it.feio.android.omninotes.alpha --agent u2 --runn
 kea2 run -s "emulator-5554" -p it.feio.android.omninotes.alpha --agent u2 --running-minutes 10 --throttle 200 --driver-name d unittest discover -s mytests/omni_notes
 ```
 
-| arg | meaning |
-| --- | --- |
-| -s | The serial of your device, which can be found by `adb devices` |
-| -p | The tested app's package name (e.g., com.example.app) | 
-| -o | The ouput directory for logs and results |
-| --agent |  {native, u2}. By default, `u2` is used and supports all the three important features of Kea2. If you hope to run the orignal Fastbot, please use `native`.|
-| --running-minutes | The time (m) to run Kea2 | 
-| --max-step | The maxium number of monkey events to send (only available in `--agent u2`) | 
-| --throttle | The delay time (ms) between two monkey events |
+| arg | meaning | default | 
+| --- | --- | --- |
+| -s | The serial of your device, which can be found by `adb devices` | |
+| -p | *The tested app's package name (e.g., com.example.app) | 
+| -o | The ouput directory for logs and results | `output` |
+| --agent |  {native, u2}. By default, `u2` is used and supports all the three important features of Kea2. If you hope to run the orignal Fastbot, please use `native`.| `u2` |
+| --running-minutes | The time (m) to run Kea2 | `10` |
+| --max-step | The maxium number of monkey events to send (only available in `--agent u2`) | `inf` |
+| --throttle | The delay time (ms) between two monkey events | `200` |
 | --driver-name | The name of driver used in the script. If `--driver-name d` is specified, you should use `d` to interact with a device, e..g, `self.d(..).click()`. |
+| --log-stamp | the stamp for log file and result file. (e.g. `--log-stamp 123` then `fastbot_123.log` and `result_123.json` will be generated.) default: current time stamp | |
 | unittest | Specify to load which scripts. This  sub-command `unittest` is fully compatible with unittest. See `python3 -m unittest -h` for more options of unittest. This option is only available in `--agent u2`.
 
 
@@ -413,6 +432,8 @@ running_mins: int = 10
 throttle: int = 200
 # the output_dir for saving logs and results
 output_dir: str = "output"
+# the stamp for log file and result file, default: current time stamp
+log_stamp: str = None
 ```
 
 ## Examining the running statistics of scripts .
@@ -457,6 +478,17 @@ Kea2 has been actively developed and maintained by the people in [ecnusse](https
 - [uiautomator2](https://github.com/openatx/uiautomator2)
 - [hypothesis](https://github.com/HypothesisWorks/hypothesis)
 
+### Relevant papers of Kea2
+
+> General and Practical Property-based Testing for Android Apps. ASE 2024. [pdf](https://dl.acm.org/doi/10.1145/3691620.3694986)
+
+> An Empirical Study of Functional Bugs in Android Apps. ISSTA 2023. [pdf](https://dl.acm.org/doi/10.1145/3597926.3598138)
+
+> Fastbot2: Reusable Automated Model-based GUI Testing for Android Enhanced by Reinforcement Learning. ASE 2022. [pdf](https://dl.acm.org/doi/10.1145/3551349.3559505)
+
+> Guided, Stochastic Model-Based GUI Testing of Android Apps. ESEC/FSE 2017.  [pdf](https://dl.acm.org/doi/10.1145/3106237.3106298)
+
+
 [^1]: 不少UI自动化测试工具提供了“自定义事件序列”能力（如[Fastbot](https://github.com/bytedance/Fastbot_Android/blob/main/handbook-cn.md#%E8%87%AA%E5%AE%9A%E4%B9%89%E4%BA%8B%E4%BB%B6%E5%BA%8F%E5%88%97) 和[AppCrawler](https://github.com/seveniruby/AppCrawler)），但在实际使用中存在不少问题，如自定义能力有限、使用不灵活等。此前不少Fastbot用户抱怨过其“自定义事件序列”在使用中的问题，如[#209](https://github.com/bytedance/Fastbot_Android/issues/209), [#225](https://github.com/bytedance/Fastbot_Android/issues/225), [#286](https://github.com/bytedance/Fastbot_Android/issues/286)等。
 
 [^2]: 在UI自动化测试过程中支持自动断言是一个很重要的能力，但几乎没有测试工具提供这样的能力。我们注意到[AppCrawler](https://ceshiren.com/t/topic/15801/5)的开发者曾经希望提供一种断言机制，得到了用户的热切响应，不少用户从21年就开始催更，但始终未能实现。

{kea2_python-0.0.1b1 → kea2_python-0.0.1b3}/kea2/adbUtils.py

@@ -1,5 +1,5 @@
 import subprocess
-from typing import List, Optional
+from typing import List, Optional, Set
 from .utils import getLogger
 
 logger = getLogger(__name__)
@@ -223,6 +223,34 @@ def remove_all_forwards(device: Optional[str] = None):
     return run_adb_command(["-s", device, "forward", "--remove-all"])
 
 
+@ensure_device
+def get_packages(device: Optional[str] = None) -> Set[str]:
+    """
+    Retrieves packages that match the specified regular expression pattern.
+    
+    Parameters:
+        pattern (str): Regular expression pattern to match package names.
+        device (str, optional): The device serial number. If None, it is resolved automatically.
+        
+    Returns:
+        set: A set of package names that match the pattern.
+    """
+    import re
+    
+    cmd = ["-s", device, "shell", "pm", "list", "packages"]
+    output = run_adb_command(cmd)
+    
+    packages = set()
+    if output:
+        compiled_pattern = re.compile(r"package:(.+)\n")
+        matches = compiled_pattern.findall(output)
+        for match in matches:
+            if match:
+                packages.add(match)
+    
+    return packages
+
+
 if __name__ == '__main__':
     # For testing: print the list of currently connected devices.
     devices = get_devices()

kea2_python-0.0.1b3/kea2/assets/fastbot_configs/widget.block.py

@@ -0,0 +1,38 @@
+from kea2.utils import Device
+from kea2.keaUtils import precondition
+
+
+def global_block_widgets(d: "Device"):
+    """
+    Specify UI widgets to be blocked globally during testing.
+    Returns a list of widgets that should be blocked from exploration.
+    This function is only available in 'u2 agent' mode.
+    """
+    # return [d(text="widgets to block"), d.xpath(".//node[@text='widget to block']")]
+    return []
+
+
+# Example of conditional blocking with precondition
+# @precondition(lambda d: d(text="In the home page").exists)
+@precondition(lambda d: False)
+def block_sth(d: "Device"):
+    # Note: Function name must start with "block_"
+    return []
+
+
+def global_block_tree(d: "Device"):
+    """
+    Specify UI widget trees to be blocked globally during testing.
+    Returns a list of root nodes whose entire subtrees will be blocked from exploration.
+    This function is only available in 'u2 agent' mode.
+    """
+    # return [d(text="trees to block"), d.xpath(".//node[@text='tree to block']")]
+    return []
+
+
+# Example of conditional tree blocking with precondition
+# @precondition(lambda d: d(text="In the home page").exists)
+@precondition(lambda d: False)
+def block_tree_sth(d: "Device"):
+    # Note: Function name must start with "block_tree_"
+    return []

{kea2_python-0.0.1b1 → kea2_python-0.0.1b3}/kea2/cli.py

@@ -99,6 +99,7 @@ def main():
     args = parser.parse_args()
 
     import logging
+    logging.basicConfig(level=logging.INFO)
     if args.debug:
         logging.basicConfig(level=logging.DEBUG)
         logger.debug("args: %s", args)

{kea2_python-0.0.1b1 → kea2_python-0.0.1b3}/kea2/keaUtils.py

@@ -119,6 +119,13 @@ class Options:
     output_dir: str = "output"
     # the stamp for log file and result file, default: current time stamp
     log_stamp: str = None
+    # the profiling period to get the coverage result.
+    profile_period: int = None
+
+    def __setattr__(self, name, value):
+        if value is None:
+            return
+        super().__setattr__(name, value)
 
     def __post_init__(self):
         if self.serial and self.Driver:
@@ -127,6 +134,17 @@ class Options:
             global LOGFILE, RESFILE
             LOGFILE = f"fastbot_{self.log_stamp}.log"
             RESFILE = f"result_{self.log_stamp}.json"
+        _check_package_installation(self.serial, self.packageNames)
+
+
+def _check_package_installation(serial, packageNames):
+    from .adbUtils import get_packages
+    installed_packages = get_packages(device=serial)
+
+    for package in packageNames:
+        if package not in installed_packages:
+            logger.error(f"package {package} not installed. Abort.")
+            raise ValueError("package not installed")
 
 
 @dataclass
@@ -257,7 +275,7 @@ def startFastbotService(options: Options) -> threading.Thread:
         "reuseq",
         "--running-minutes", f"{options.running_mins}",
         "--throttle", f"{options.throttle}",
-        "--bugreport", "--output-directory", "/sdcard/fastbot_report"
+        "--bugreport", "--output-directory", "/sdcard/fastbot_report",
         "-v", "-v", "-v"
     ]
 
@@ -287,7 +305,8 @@ class KeaTestRunner(TextTestRunner):
     resultclass: JsonResult
     allProperties: PropertyStore
     options: Options = None
-    _block_widgets_funcs = None
+    _block_funcs: Dict[Literal["widgets", "trees"], List[Callable]] = None
+    # _block_trees_funcs = None
 
     @classmethod
     def setOptions(cls, options: Options):
@@ -354,18 +373,20 @@ class KeaTestRunner(TextTestRunner):
                 check_alive(port=self.scriptDriver.lport)
 
                 end_by_remote = False
-                step = 0
-                while step < self.options.maxStep:
+                self.stepsCount = 0
+                while self.stepsCount < self.options.maxStep:
 
-                    step += 1
+                    self.stepsCount += 1
                     print("[INFO] Sending monkeyEvent {}".format(
-                        f"({step} / {self.options.maxStep})" if self.options.maxStep != float("inf")
-                        else f"({step})"
+                        f"({self.stepsCount} / {self.options.maxStep})" if self.options.maxStep != float("inf")
+                        else f"({self.stepsCount})"
                         )
                     , flush=True)
 
                     try:
-                        propsSatisfiedPrecond = self.getValidProperties(result)
+                        xml_raw = self.stepMonkey()
+                        stat = self._getStat()
+                        propsSatisfiedPrecond = self.getValidProperties(xml_raw, result)
                     except requests.ConnectionError:
                         print(
                             "[INFO] Exploration times up (--running-minutes)."
@@ -413,7 +434,6 @@ class KeaTestRunner(TextTestRunner):
 
             print(f"Finish sending monkey events.", flush=True)
             log_watcher.close()
-            self.tearDown()
 
         # Source code from unittest Runner
         # process the result
@@ -455,14 +475,19 @@ class KeaTestRunner(TextTestRunner):
         """
         send a step monkey request to the server and get the xml string.
         """
-        block_widgets: List[str] = self._getBlockedWidgets()
+        block_dict = self._getBlockedWidgets()
+        block_widgets: List[str] = block_dict['widgets']
+        block_trees: List[str] = block_dict['trees']
         URL = f"http://localhost:{self.scriptDriver.lport}/stepMonkey"
         logger.debug(f"Sending request: {URL}")
         logger.debug(f"Blocking widgets: {block_widgets}")
+        logger.debug(f"Blocking trees: {block_trees}")
         r = requests.post(
             url=URL,
             json={
-                "block_widgets": block_widgets
+                "steps_count": self.stepsCount,
+                "block_widgets": block_widgets,
+                "block_trees": block_trees
             }
         )
 
@@ -481,9 +506,8 @@ class KeaTestRunner(TextTestRunner):
         res = r.content.decode(encoding="utf-8")
         print(f"[Server INFO] {res}", flush=True)
 
-    def getValidProperties(self, result: JsonResult) -> PropertyStore:
+    def getValidProperties(self, xml_raw: str, result: JsonResult) -> PropertyStore:
 
-        xml_raw = self.stepMonkey()
         staticCheckerDriver = self.options.Driver.getStaticChecker(hierarchy=xml_raw)
 
         validProps: PropertyStore = dict()
@@ -513,6 +537,15 @@ class KeaTestRunner(TextTestRunner):
                 validProps[propName] = test
         return validProps
 
+    def _getStat(self):
+        # profile when reaching the profile period
+        if (self.options.profile_period and 
+            self.stepsCount % self.options.profile_period == 0
+        ):
+            URL = f"http://localhost:{self.scriptDriver.lport}/getStat"
+            r = requests.get(URL)
+            res = json.loads(r.content)
+
     def collectAllProperties(self, test: TestSuite):
         """collect all the properties to prepare for PBT
         """
@@ -548,17 +581,24 @@ class KeaTestRunner(TextTestRunner):
                 # save it into allProperties for PBT
                 self.allProperties[testMethodName] = t
                 print(f"[INFO] Load property: {getFullPropName(t)}", flush=True)
-    
+
     @property
     def _blockWidgetFuncs(self):
-        if self._block_widgets_funcs is None:
-            self._block_widgets_funcs = list()
+        """
+        load and process blocking functions from widget.block.py configuration file.
+
+        Returns:
+            dict: A dictionary containing two lists:
+                - 'widgets': List of functions that block individual widgets
+                - 'trees': List of functions that block widget trees
+        """
+        if self._block_funcs is None:
+            self._block_funcs = {"widgets": list(), "trees": list()}
             root_dir = getProjectRoot()
             if root_dir is None or not os.path.exists(
-                file_block_widgets := root_dir / "configs" / "widget.block.py"
+                    file_block_widgets := root_dir / "configs" / "widget.block.py"
             ):
                 print(f"[WARNING] widget.block.py not find", flush=True)
-            
 
             def __get_block_widgets_module():
                 import importlib.util
@@ -572,43 +612,81 @@ class KeaTestRunner(TextTestRunner):
 
             import inspect
             for func_name, func in inspect.getmembers(mod, inspect.isfunction):
-                if func_name.startswith("block_") or func_name == "global_block_widgets":
+                if func_name == "global_block_widgets":
+                    self._block_funcs["widgets"].append(func)
+                    setattr(func, PRECONDITIONS_MARKER, (lambda d: True,))
+                    continue
+                if func_name == "global_block_tree":
+                    self._block_funcs["trees"].append(func)
+                    setattr(func, PRECONDITIONS_MARKER, (lambda d: True,))
+                    continue
+                if func_name.startswith("block_") and not func_name.startswith("block_tree_"):
                     if getattr(func, PRECONDITIONS_MARKER, None) is None:
-                        if func_name.startswith("block_"):
-                            logger.warning(f"No precondition in block widget function: {func_name}. Default globally active.")
-                        setattr(func, PRECONDITIONS_MARKER, (lambda d: True, ))
-                    self._block_widgets_funcs.append(func)
+                        logger.warning(f"No precondition in block widget function: {func_name}. Default globally active.")
+                        setattr(func, PRECONDITIONS_MARKER, (lambda d: True,))
+                    self._block_funcs["widgets"].append(func)
+                    continue
+                if func_name.startswith("block_tree_"):
+                    if getattr(func, PRECONDITIONS_MARKER, None) is None:
+                        logger.warning(f"No precondition in block tree function: {func_name}. Default globally active.")
+                        setattr(func, PRECONDITIONS_MARKER, (lambda d: True,))
+                    self._block_funcs["trees"].append(func)
+
+        return self._block_funcs
 
-        return self._block_widgets_funcs
 
     def _getBlockedWidgets(self):
-        blocked_widgets = list()
-        for func in self._blockWidgetFuncs:
+        """
+           Executes all blocking functions to get lists of widgets and trees to be blocked during testing.
+
+           Returns:
+               dict: A dictionary containing:
+                   - 'widgets': List of XPath strings for individual widgets to block
+                   - 'trees': List of XPath strings for widget trees to block
+           """
+        def _get_xpath_widgets(func):
+            blocked_set = set()
             try:
                 script_driver = self.options.Driver.getScriptDriver()
-                preconds = getattr(func, PRECONDITIONS_MARKER)
-                if all([precond(script_driver) for precond in preconds]):
+                preconds = getattr(func, PRECONDITIONS_MARKER, [])
+                if all(precond(script_driver) for precond in preconds):
                     _widgets = func(self.options.Driver.getStaticChecker())
-                    if not isinstance(_widgets, list):
-                        _widgets = [_widgets]
+                    _widgets = _widgets if isinstance(_widgets, list) else [_widgets]
                     for w in _widgets:
                         if isinstance(w, StaticU2UiObject):
-                            blocked_widgets.append(w._getXPath(w.selector))
+                            xpath = w._getXPath(w.selector)
+                            blocked_set.add(xpath)  # 集合去重
                         elif isinstance(w, u2.xpath.XPathSelector):
-                            def getXPathRepr(w):
-                                return w._parent.xpath
-                            blocked_widgets.append(getXPathRepr(w))
+                            xpath = w._parent.xpath
+                            blocked_set.add(xpath)
                         else:
                             logger.warning(f"{w} Not supported")
-                    # blocked_widgets.extend([
-                    #     w._getXPath(w.selector) for w in _widgets
-                    # ])
             except Exception as e:
-                logger.error(f"error when getting blocked widgets: {e}")
-                import traceback
+                logger.error(f"Error processing blocked widgets: {e}")
                 traceback.print_exc()
+            return blocked_set
+
+        res = {
+            "widgets": set(),
+            "trees": set()
+        }
+
+
+        for func in self._blockWidgetFuncs["widgets"]:
+            widgets = _get_xpath_widgets(func)
+            res["widgets"].update(widgets)
+
+
+        for func in self._blockWidgetFuncs["trees"]:
+            trees = _get_xpath_widgets(func)
+            res["trees"].update(trees)
+
+
+        res["widgets"] = list(res["widgets"] - res["trees"])
+        res["trees"] = list(res["trees"])
+
+        return res
 
-        return blocked_widgets
 
     def __del__(self):
         """tearDown method. Cleanup the env.

{kea2_python-0.0.1b1 → kea2_python-0.0.1b3}/kea2/kea_launcher.py

@@ -83,6 +83,14 @@ def _set_runner_parser(subparsers: "argparse._SubParsersAction[argparse.Argument
         required=False,
         help="the stamp for log file and result file, default: current time stamp",
     )
+    
+    parser.add_argument(
+        "--profile-period",
+        dest="profile_period",
+        type=int,
+        required=False,
+        help="Steps to profile the testing statistics.",
+    )
 
     parser.add_argument(
         "extra",
@@ -120,6 +128,7 @@ def parse_args(argv: List):
     args = parser.parse_args(argv)
     return args
 
+
 def _sanitize_args(args):
     if args.agent == "u2" and not args.driver_name:
         if args.extra == []:
@@ -127,6 +136,7 @@ def _sanitize_args(args):
         else:
             raise ValueError("--driver-name should be specified when customizing script in --agent u2")
 
+
 def run(args=None):
     if args is None:
         args = parse_args(sys.argv[1:])
@@ -144,10 +154,11 @@ def run(args=None):
         Driver=U2Driver,
         packageNames=args.package_names,
         serial=args.serial,
-        running_mins=args.running_minutes if args.running_minutes else 10,
-        maxStep=args.max_step if args.max_step else 500,
-        throttle=args.throttle_ms if args.throttle_ms else 200,
-        log_stamp=args.log_stamp
+        running_mins=args.running_minutes,
+        maxStep=args.max_step,
+        throttle=args.throttle_ms,
+        log_stamp=args.log_stamp,
+        profile_period=args.profile_period,
     )
 
     KeaTestRunner.setOptions(options)

{kea2_python-0.0.1b1 → kea2_python-0.0.1b3}/kea2/logWatcher.py

@@ -46,17 +46,19 @@ class LogWatcher:
                     exception_body + 
                     "\nSee fastbot.log for details."
                 )
-        statistic_match = PATTERN_STATISTIC.search(buffer)
-        if statistic_match:
-            statistic_body = statistic_match.group(1).strip()
-            if statistic_body:
-                print(
-                    "[INFO] Fastbot exit:\n" + 
-                    statistic_body
-                , flush=True)
+        if self.end_flag:
+            statistic_match = PATTERN_STATISTIC.search(buffer)
+            if statistic_match:
+                statistic_body = statistic_match.group(1).strip()
+                if statistic_body:
+                    print(
+                        "[INFO] Fastbot exit:\n" + 
+                        statistic_body
+                    , flush=True)
 
     def __init__(self, log_file):
         self.log_file = log_file
+        self.end_flag = False
 
         threading.excepthook = thread_excepthook
         t = threading.Thread(target=self.watcher, daemon=True)
@@ -64,6 +66,7 @@ class LogWatcher:
     
     def close(self):
         time.sleep(0.2) # wait for the written logfile close
+        self.end_flag = True
         self.read_log()
 
 

{kea2_python-0.0.1b1 → kea2_python-0.0.1b3}/kea2/u2Driver.py

@@ -235,7 +235,7 @@ class U2StaticDevice(u2.Device):
     
     def __getattr__(self, attr):
         """Proxy other methods to script_driver"""
-        # logger.debug(f"{attr} not exists in static checker, proxy to script_driver.")
+        logger.debug(f"{attr} not exists in static checker, proxy to script_driver.")
         return getattr(self._script_driver, attr)
 
 class _XPathEntry(u2.xpath.XPathEntry):

{kea2_python-0.0.1b1 → kea2_python-0.0.1b3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "Kea2-python"
-version = "0.0.1b1"
+version = "0.0.1b3"
 description = "A python library for supporting and customizing automated UI testing for mobile apps"
 readme = "README.md"
 requires-python = ">=3.8"
@@ -19,4 +19,4 @@ kea2 = "kea2.cli:main"
 include = ["kea2"]
 
 [tool.setuptools.package-data]
-kea2 = ["assets/**/*"]
+kea2 = ["assets/**/*"]

kea2_python-0.0.1b1/kea2/assets/fastbot_configs/widget.block.py

@@ -1,18 +0,0 @@
-from kea2.utils import Device
-from kea2.keaUtils import precondition
-
-
-def global_block_widgets(d: "Device"):
-    """
-    global block widgets.
-    return the widgets you want to block globally
-    only available in mode `u2 agent`
-    """
-    return []
-
-
-# conditional block list
-@precondition(lambda d: d(text="In the home page").exists)
-def block_sth(d: "Device"):
-    # Important: function shold starts with "block_"
-    return [d(text="widgets to block"), d.xpath(".//node[@text='widget to block']")]