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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: Kea2-python
-Version: 0.0.1a6
+Version: 0.0.1b1
 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
@@ -12,6 +12,14 @@ Dynamic: license-file
 
 # Introduction 
 
+[![PyPI](https://img.shields.io/pypi/v/kea2-python.svg)](https://pypi.python.org/pypi/kea2-python)
+[![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:
@@ -297,16 +305,30 @@ 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) and basic xpath (No chain call like `.xpath().xpath()`) in uiautomator2. The Script body in the function fully support uiautomator2.
-
+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` |
-| **XPath** | `d.xpath(".//[@text='1']")` | `d.xpath(".//[@text='1']").xpath(".//[@text]='2'")` |
 
 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
 

kea2_python-0.0.1a6/README.md → kea2_python-0.0.1b1/PKG-INFO

@@ -1,5 +1,25 @@
+Metadata-Version: 2.4
+Name: Kea2-python
+Version: 0.0.1b1
+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
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: rtree>=1.3.0
+Requires-Dist: uiautomator2>=3.2.9
+Dynamic: license-file
+
 # Introduction 
 
+[![PyPI](https://img.shields.io/pypi/v/kea2-python.svg)](https://pypi.python.org/pypi/kea2-python)
+[![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:
@@ -285,16 +305,30 @@ 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) and basic xpath (No chain call like `.xpath().xpath()`) in uiautomator2. The Script body in the function fully support uiautomator2.
-
+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` |
-| **XPath** | `d.xpath(".//[@text='1']")` | `d.xpath(".//[@text='1']").xpath(".//[@text]='2'")` |
 
 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
 

kea2_python-0.0.1a6/Kea2_python.egg-info/PKG-INFO → kea2_python-0.0.1b1/README.md

@@ -1,17 +1,13 @@
-Metadata-Version: 2.4
-Name: Kea2-python
-Version: 0.0.1a6
-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
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: rtree>=1.3.0
-Requires-Dist: uiautomator2>=3.2.9
-Dynamic: license-file
-
 # Introduction 
 
+[![PyPI](https://img.shields.io/pypi/v/kea2-python.svg)](https://pypi.python.org/pypi/kea2-python)
+[![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:
@@ -297,16 +293,30 @@ 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) and basic xpath (No chain call like `.xpath().xpath()`) in uiautomator2. The Script body in the function fully support uiautomator2.
-
+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` |
-| **XPath** | `d.xpath(".//[@text='1']")` | `d.xpath(".//[@text='1']").xpath(".//[@text]='2'")` |
 
 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
 

kea2_python-0.0.1b1/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.1a6 → kea2_python-0.0.1b1}/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.1a6 → kea2_python-0.0.1b1}/kea2/adbUtils.py

@@ -1,5 +1,9 @@
 import subprocess
 from typing import List, Optional
+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:

{kea2_python-0.0.1a6 → kea2_python-0.0.1b1}/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.1a6 → kea2_python-0.0.1b1}/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
 

{kea2_python-0.0.1a6 → kea2_python-0.0.1b1}/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,6 +117,16 @@ 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
+
+    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"
 
 
 @dataclass
@@ -147,6 +178,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:
     """
@@ -270,6 +304,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):
 
@@ -329,7 +365,7 @@ class KeaTestRunner(TextTestRunner):
                     , flush=True)
 
                     try:
-                        propsSatisfiedPrecond = self.getValidProperties()
+                        propsSatisfiedPrecond = self.getValidProperties(result)
                     except requests.ConnectionError:
                         print(
                             "[INFO] Exploration times up (--running-minutes)."
@@ -421,6 +457,8 @@ 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={
@@ -436,12 +474,14 @@ 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, result: JsonResult) -> PropertyStore:
 
         xml_raw = self.stepMonkey()
         staticCheckerDriver = self.options.Driver.getStaticChecker(hierarchy=xml_raw)
@@ -466,6 +506,10 @@ 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
 
@@ -566,6 +610,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.1a6 → kea2_python-0.0.1b1}/kea2/kea_launcher.py

@@ -76,6 +76,14 @@ 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(
         "extra",
         nargs=argparse.REMAINDER,
@@ -130,7 +138,6 @@ def run(args=None):
 
     from kea2 import KeaTestRunner, Options
     from kea2.u2Driver import U2Driver
-    U2Driver.setDeviceSerial(args.serial)
     options = Options(
         agent=args.agent,
         driverName=args.driver_name,
@@ -139,7 +146,8 @@ def run(args=None):
         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
+        throttle=args.throttle_ms if args.throttle_ms else 200,
+        log_stamp=args.log_stamp
     )
 
     KeaTestRunner.setOptions(options)

{kea2_python-0.0.1a6 → kea2_python-0.0.1b1}/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
@@ -88,7 +92,9 @@ class StaticU2UiObject(u2.UiObject):
     def _transferU2Keys(self, originKey):
         filterDict = {
             "resourceId": "resource-id",
-            "description": "content-desc"
+            "description": "content-desc",
+            "className": "class",
+            "longClickable": "long-clickable",
         }
         if filterDict.get(originKey, None):
             return filterDict[originKey]
@@ -229,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):
@@ -237,6 +244,7 @@ class _XPathEntry(u2.xpath.XPathEntry):
         super().__init__(d)
         
     def __call__(self, xpath, source = None):
+        # TODO fully support xpath in widget.block.py
         self.xpath = xpath
         return super().__call__(xpath, source)
 
@@ -290,6 +298,10 @@ class U2Driver(AbstractDriver):
             self.staticChecker = U2StaticChecker()
         return self.staticChecker.getInstance(hierarchy)
 
+    @classmethod
+    def tearDown(self):
+        self.scriptDriver.tearDown()
+
 
 """
 Other Utils
@@ -308,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.1a6 → kea2_python-0.0.1b1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "Kea2-python"
-version = "0.0.1a6"
+version = "0.0.1b1"
 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.1a6/kea2/__init__.py

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