Kea2-python 0.0.1b0__tar.gz → 0.0.1b2__tar.gz

{kea2_python-0.0.1b0 → kea2_python-0.0.1b2}/Kea2_python.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: Kea2-python
-Version: 0.0.1b0
+Version: 0.0.1b2
 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
@@ -16,6 +16,10 @@ Dynamic: license-file
 [![PyPI Downloads](https://static.pepy.tech/badge/kea2-python)](https://pepy.tech/projects/kea2-python)
 ![Python](https://img.shields.io/badge/python-3.8%2B-blue)
 
+<div>
+    <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 has three important features:
@@ -57,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 
@@ -300,31 +305,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
 
@@ -349,16 +329,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, 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`.
 
 
@@ -421,6 +402,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 .
@@ -465,6 +448,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.1b0 → kea2_python-0.0.1b2}/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.1b0 → kea2_python-0.0.1b2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: Kea2-python
-Version: 0.0.1b0
+Version: 0.0.1b2
 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
@@ -16,6 +16,10 @@ Dynamic: license-file
 [![PyPI Downloads](https://static.pepy.tech/badge/kea2-python)](https://pepy.tech/projects/kea2-python)
 ![Python](https://img.shields.io/badge/python-3.8%2B-blue)
 
+<div>
+    <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 has three important features:
@@ -57,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 
@@ -300,31 +305,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
 
@@ -349,16 +329,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, 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`.
 
 
@@ -421,6 +402,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 .
@@ -465,6 +448,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.1b0 → kea2_python-0.0.1b2}/README.md

@@ -4,6 +4,10 @@
 [![PyPI Downloads](https://static.pepy.tech/badge/kea2-python)](https://pepy.tech/projects/kea2-python)
 ![Python](https://img.shields.io/badge/python-3.8%2B-blue)
 
+<div>
+    <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 has three important features:
@@ -45,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 
@@ -288,31 +293,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
 
@@ -337,16 +317,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, 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`.
 
 
@@ -409,6 +390,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 .
@@ -453,6 +436,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.1b2/kea2/__init__.py

@@ -0,0 +1,4 @@
+from .keaUtils import KeaTestRunner, precondition, prob, max_tries, Options
+
+import logging
+logging.basicConfig(level=logging.DEBUG)

{kea2_python-0.0.1b0 → kea2_python-0.0.1b2}/kea2/absDriver.py

@@ -50,3 +50,7 @@ class AbstractDriver(abc.ABC):
     @abc.abstractmethod
     def getStaticChecker(self, hierarchy) -> AbstractStaticChecker:
         pass
+
+    @classmethod
+    @abc.abstractmethod
+    def tearDown(self): ...

{kea2_python-0.0.1b0 → kea2_python-0.0.1b2}/kea2/adbUtils.py

@@ -1,5 +1,9 @@
 import subprocess
-from typing import List, Optional
+from typing import List, Optional, Set
+from .utils import getLogger
+
+logger = getLogger(__name__)
+
 
 def run_adb_command(cmd: List[str], timeout=10):
     """
@@ -13,6 +17,7 @@ def run_adb_command(cmd: List[str], timeout=10):
         str: The standard output from the command. If an error occurs, returns None.
     """
     full_cmd = ["adb"] + cmd
+    logger.debug(f"{' '.join(full_cmd)}")
     try:
         result = subprocess.run(full_cmd, capture_output=True, text=True, timeout=timeout)
         if result.returncode != 0:
@@ -218,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.1b0 → kea2_python-0.0.1b2}/kea2/assets/quicktest.py

@@ -57,7 +57,7 @@ PACKAGE_NAME = "it.feio.android.omninotes.alpha"
 FILE_NAME = "omninotes.apk"
 
 
-def check_installation():
+def check_installation(serial=None):
     import os
     from pathlib import Path
     if not os.path.exists(Path(".") / FILE_NAME):
@@ -65,7 +65,7 @@ def check_installation():
         import urllib.request
         urllib.request.urlretrieve(URL, FILE_NAME)
 
-    d = u2.connect()
+    d = u2.connect(serial)
     # automatically install omni-notes
     if PACKAGE_NAME not in d.app_list():
         print("[INFO] Installing omninotes.", flush=True)
@@ -74,7 +74,7 @@ def check_installation():
 
 
 if __name__ == "__main__":
-    check_installation()
+    check_installation(serial=None)
     KeaTestRunner.setOptions(
         Options(
             driverName="d",

{kea2_python-0.0.1b0 → kea2_python-0.0.1b2}/kea2/cli.py

@@ -3,7 +3,7 @@
 
 from __future__ import absolute_import, print_function
 import sys
-from kea2.utils import getProjectRoot, getLogger
+from .utils import getProjectRoot, getLogger
 from .kea_launcher import run
 import argparse
 
@@ -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.1b0 → kea2_python-0.0.1b2}/kea2/keaUtils.py

@@ -19,9 +19,10 @@ from .utils import TimeStamp, getProjectRoot, getLogger
 from .u2Driver import StaticU2UiObject
 import uiautomator2 as u2
 import types
+
 PRECONDITIONS_MARKER = "preconds"
 PROP_MARKER = "prop"
-
+MAX_TRIES_MARKER = "max_tries"
 
 logger = getLogger(__name__)
 
@@ -30,14 +31,14 @@ logger = getLogger(__name__)
 PropName = NewType("PropName", str)
 PropertyStore = NewType("PropertyStore", Dict[PropName, TestCase])
 
-TIME_STAMP = TimeStamp().getTimeStamp()
-LOGFILE = f"fastbot_{TIME_STAMP}.log"
-RESFILE = f"result_{TIME_STAMP}.json"
+STAMP = TimeStamp().getTimeStamp()
+LOGFILE = f"fastbot_{STAMP}.log"
+RESFILE = f"result_{STAMP}.json"
 
 def precondition(precond: Callable[[Any], bool]) -> Callable:
     """the decorator @precondition
 
-    The precondition specifies when the property could be executed.
+    @precondition specifies when the property could be executed.
     A property could have multiple preconditions, each of which is specified by @precondition.
     """
     def accept(f):
@@ -56,7 +57,7 @@ def precondition(precond: Callable[[Any], bool]) -> Callable:
 def prob(p: float):
     """the decorator @prob
 
-    The prob specify the propbability of execution when a property is satisfied.
+    @prob specify the propbability of execution when a property is satisfied.
     """
     p = float(p)
     if not 0 < p <= 1.0:
@@ -73,6 +74,26 @@ def prob(p: float):
     return accept
 
 
+def max_tries(n: int):
+    """the decorator @max_tries
+
+    @max_tries specify the maximum tries of executing a property.
+    """
+    n = int(n)
+    if not n > 0:
+        raise ValueError("The maxium tries should be a positive integer.")
+    def accept(f):
+        @wraps(f)
+        def precondition_wrapper(*args, **kwargs):
+            return f(*args, **kwargs)
+
+        setattr(precondition_wrapper, MAX_TRIES_MARKER, n)
+
+        return precondition_wrapper
+
+    return accept
+
+
 @dataclass
 class Options:
     """
@@ -96,10 +117,34 @@ class Options:
     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
+    # 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:
             self.Driver.setDeviceSerial(self.serial)
+        if self.log_stamp:
+            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
@@ -151,6 +196,9 @@ class JsonResult(TextTestResult):
         super().addError(test, err)
         self.res[getFullPropName(test)].error += 1
 
+    def getExcuted(self, test: TestCase):
+        return self.res[getFullPropName(test)].executed
+
 
 def activateFastbot(options: Options, port=None) -> threading.Thread:
     """
@@ -227,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"
     ]
 
@@ -274,6 +322,8 @@ class KeaTestRunner(TextTestRunner):
         global LOGFILE, RESFILE
         LOGFILE = output_dir / Path(LOGFILE)
         RESFILE = output_dir / Path(RESFILE)
+        logger.debug(f"Log file: {LOGFILE}")
+        logger.debug(f"Result file: {RESFILE}")
 
     def run(self, test):
 
@@ -322,18 +372,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()
+                        xml_raw = self.stepMonkey()
+                        stat = self._getStat()
+                        propsSatisfiedPrecond = self.getValidProperties(xml_raw, result)
                     except requests.ConnectionError:
                         print(
                             "[INFO] Exploration times up (--running-minutes)."
@@ -425,9 +477,12 @@ class KeaTestRunner(TextTestRunner):
         """
         block_widgets: List[str] = self._getBlockedWidgets()
         URL = f"http://localhost:{self.scriptDriver.lport}/stepMonkey"
+        logger.debug(f"Sending request: {URL}")
+        logger.debug(f"Blocking widgets: {block_widgets}")
         r = requests.post(
             url=URL,
             json={
+                "steps_count": self.stepsCount,
                 "block_widgets": block_widgets
             }
         )
@@ -440,14 +495,15 @@ class KeaTestRunner(TextTestRunner):
         """
         send a stop monkey request to the server and get the xml string.
         """
-        r = requests.get(f"http://localhost:{self.scriptDriver.lport}/stopMonkey")
+        URL = f"http://localhost:{self.scriptDriver.lport}/stopMonkey"
+        logger.debug(f"Sending request: {URL}")
+        r = requests.get(URL)
 
         res = r.content.decode(encoding="utf-8")
         print(f"[Server INFO] {res}", flush=True)
 
-    def getValidProperties(self) -> 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()
@@ -470,9 +526,22 @@ class KeaTestRunner(TextTestRunner):
                     break
             # if all the precond passed. make it the candidate prop.
             if valid:
+                logger.debug(f"precond satisfied: {getFullPropName(test)}")
+                if result.getExcuted(test) >= getattr(prop, MAX_TRIES_MARKER, float("inf")):
+                    logger.debug(f"{getFullPropName(test)} has reached its max_tries. Skip.")
+                    continue
                 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
         """
@@ -570,6 +639,8 @@ class KeaTestRunner(TextTestRunner):
 
         return blocked_widgets
 
-    def tearDown(self):
-        # TODO Add tearDown method (remove local port, etc.)
-        pass
+    def __del__(self):
+        """tearDown method. Cleanup the env.
+        """
+        if self.options.Driver:
+            self.options.Driver.tearDown()

{kea2_python-0.0.1b0 → kea2_python-0.0.1b2}/kea2/kea_launcher.py

@@ -76,6 +76,22 @@ def _set_runner_parser(subparsers: "argparse._SubParsersAction[argparse.Argument
         help="The name of driver in script.",
     )
 
+    parser.add_argument(
+        "--log-stamp",
+        dest="log_stamp",
+        type=str,
+        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",
         nargs=argparse.REMAINDER,
@@ -112,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 == []:
@@ -119,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:])
@@ -136,9 +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
+        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.1b0 → kea2_python-0.0.1b2}/kea2/u2Driver.py

@@ -8,7 +8,7 @@ from typing import Dict, List, Union
 from lxml import etree
 from .absDriver import AbstractScriptDriver, AbstractStaticChecker, AbstractDriver
 from .adbUtils import list_forwards, remove_forward, create_forward
-from .utils import TimeStamp
+from .utils import TimeStamp, getLogger
 
 TIME_STAMP = TimeStamp().getTimeStamp()
 
@@ -16,6 +16,8 @@ import logging
 logging.getLogger("urllib3").setLevel(logging.INFO)
 logging.getLogger("uiautomator2").setLevel(logging.INFO)
 
+logger = getLogger(__name__)
+
 """
 The definition of U2ScriptDriver
 """
@@ -57,16 +59,13 @@ class U2ScriptDriver(AbstractScriptDriver):
                 setattr(self.d._dev, "msg", "meta")
                 print(f"[U2] local port: {lport}", flush=True)
                 return lport
-            
+
             self._remove_remote_port(8090)
             self.d.lport = get_u2_forward_port()
             self._remove_remote_port(9008)
 
         return self.d
 
-    def tearDown(self):
-        self.d.stop_uiautomator()
-
     def _remove_remote_port(self, port:int):
         """remove the forward port
         """
@@ -76,6 +75,11 @@ class U2ScriptDriver(AbstractScriptDriver):
                 forward_local = forward["local"]
                 remove_forward(local_spec=forward_local, device=self.deviceSerial)
 
+    def tearDown(self):
+        logger.debug("U2Driver tearDown: stop_uiautomator")
+        self.d.stop_uiautomator()
+        logger.debug("U2Driver tearDown: remove forward")
+        self._remove_remote_port(8090)
 
 """
 The definition of U2StaticChecker
@@ -231,6 +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.")
         return getattr(self._script_driver, attr)
 
 class _XPathEntry(u2.xpath.XPathEntry):
@@ -293,6 +298,10 @@ class U2Driver(AbstractDriver):
             self.staticChecker = U2StaticChecker()
         return self.staticChecker.getInstance(hierarchy)
 
+    @classmethod
+    def tearDown(self):
+        self.scriptDriver.tearDown()
+
 
 """
 Other Utils
@@ -311,6 +320,7 @@ def forward_port(self, remote: Union[int, str]) -> int:
                 return int(f.local[len("tcp:") :])
         local_port = get_free_port()
         self.forward("tcp:" + str(local_port), remote)
+        logger.debug(f"forwading port: tcp:{local_port} -> {remote}")
         return local_port
 
 

{kea2_python-0.0.1b0 → kea2_python-0.0.1b2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "Kea2-python"
-version = "0.0.1b0"
+version = "0.0.1b2"
 description = "A python library for supporting and customizing automated UI testing for mobile apps"
 readme = "README.md"
 requires-python = ">=3.8"

kea2_python-0.0.1b0/kea2/__init__.py

@@ -1,4 +0,0 @@
-from .keaUtils import KeaTestRunner, precondition, prob, Options
-
-import logging
-logging.basicConfig(level=logging.DEBUG)