Kea2-python 0.0.1a0__py3-none-any.whl → 0.0.1a2__py3-none-any.whl

kea2/assets/fastbot_configs/widget.block.py

@@ -1,22 +1,18 @@
-from kea2.utils import precondition
-from uiautomator2 import Device
+from kea2.utils import Device
+from kea2.keaUtils import precondition
 
 
-@precondition(lambda d:
-    d(text="Setting")
-)
-def sample_block_list(d: "Device"):
-    return d(text="Omni Notes Alpha").exists
+def global_block_widgets(d: "Device"):
+    """
+    global block widgets.
+    return the widgets you want to block globally
+    only available in mode `u2 agent`
+    """
+    return []
 
 
-if __name__ == "__main__":
-    from kea2.utils import BLOCK_WIDGET
-    func = getattr(sample_block_list, BLOCK_WIDGET)
-    import uiautomator2 as u2
-    d = u2.connect()
-    blocked_widgets = func(d)
-    if isinstance(blocked_widgets, u2.UiObject):
-        blocked_widgets = [blocked_widgets]
-    if not all([isinstance(w, u2.UiObject) for w in blocked_widgets]):
-        raise TypeError(f"Invalid widgets block list in {sample_block_list}")
-    
+# 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']")]

kea2/assets/quickstart.py

@@ -73,7 +73,15 @@ def check_installation():
     d.stop_uiautomator()
 
 
+def _get_agent():
+    import sys
+    if len(sys.argv) == 0 or sys.argv[1] == "u2":
+        return "u2"
+    return "native"
+
 if __name__ == "__main__":
+    
+    AGENT=_get_agent()
     check_installation()
     KeaTestRunner.setOptions(
         Options(
@@ -84,7 +92,7 @@ if __name__ == "__main__":
             maxStep=5000,
             # running_mins=10,  # specify the maximal running time in minutes, default value is 10m
             # throttle=200,   # specify the throttle in milliseconds, default value is 200ms
-            # agent='native'  # 'native' for running the vanilla Fastbot, 'u2' for running Kea2
+            agent=AGENT  # 'native' for running the vanilla Fastbot, 'u2' for running Kea2
         )
     )
     unittest.main(testRunner=KeaTestRunner)

kea2/cli.py

@@ -2,6 +2,7 @@
 # cli.py
 
 from __future__ import absolute_import, print_function
+import sys
 from kea2.utils import getProjectRoot, getLogger
 from .kea_launcher import run
 import argparse
@@ -43,9 +44,7 @@ def cmd_run(args):
     if base_dir is None:
         logger.error("kea2 project not initialized. Use `kea2 init`.")
         return
-    argv = [__file__]
-    argv.extend(args.args)
-    run(argv)
+    run(args)
 
 
 def cmd_install(args):
@@ -83,14 +82,14 @@ _commands = [
         command="init",
         help="init the Kea2 project in current directory",
     ),
-    dict(
-        action=cmd_run,
-        command="run",
-        help="run kea2",
-        flags=[
-            dict(args=["args"], nargs=argparse.REMAINDER, help="args for kea2 run"),
-        ],
-    ),
+    # dict(
+    #     action=cmd_run,
+    #     command="run",
+    #     help="run kea2",
+    #     flags=[
+    #         dict(args=["args"], nargs=argparse.REMAINDER),
+    #     ],
+    # ),
     # dict(
     #     action=cmd_install,
     #     command="",
@@ -157,11 +156,17 @@ def main():
             kwargs.pop('args', None)
             sp.add_argument(*args, **kwargs)
 
+    from .kea_launcher import _set_driver_parser
+    _set_driver_parser(subparser)
+    actions["run"] = cmd_run
+    if sys.argv[1:] == ["run"]:
+        sys.argv.append("-h")
     args = parser.parse_args()
-    
 
+    import logging
+    logging.getLogger("urllib3").setLevel(logging.INFO)
+    logging.getLogger("uiautomator2").setLevel(logging.INFO)
     if args.debug:
-        import logging
         logging.basicConfig(level=logging.DEBUG)
         logger.debug("args: %s", args)
 

kea2/keaUtils.py

@@ -15,6 +15,8 @@ from time import sleep
 from .adbUtils import push_file
 from .logWatcher import LogWatcher
 from .utils import TimeStamp, getProjectRoot, getLogger
+from .u2Driver import StaticU2UiObject
+import uiautomator2 as u2
 import types
 PRECONDITIONS_MARKER = "preconds"
 PROP_MARKER = "prop"
@@ -404,8 +406,14 @@ class KeaTestRunner(TextTestRunner):
         """
         send a step monkey request to the server and get the xml string.
         """
-        block_widgets = self._getBlockedWidgets()
-        r = requests.get(f"http://localhost:{self.scriptDriver.lport}/stepMonkey")
+        block_widgets: List[str] = self._getBlockedWidgets()
+        URL = f"http://localhost:{self.scriptDriver.lport}/stepMonkey"
+        r = requests.post(
+            url=URL,
+            json={
+                "block_widgets": block_widgets
+            }
+        )
 
         res = json.loads(r.content)
         xml_raw = res["result"]
@@ -479,7 +487,7 @@ class KeaTestRunner(TextTestRunner):
                 print(f"[INFO] Load property: {getFullPropName(t)}", flush=True)
     
     @property
-    def blockList(self):
+    def _blockWidgetFuncs(self):
         if self._block_widgets_funcs is None:
             self._block_widgets_funcs = list()
             root_dir = getProjectRoot()
@@ -512,7 +520,7 @@ class KeaTestRunner(TextTestRunner):
 
     def _getBlockedWidgets(self):
         blocked_widgets = list()
-        for func in self.blockList:
+        for func in self._blockWidgetFuncs:
             try:
                 script_driver = self.options.Driver.getScriptDriver()
                 preconds = getattr(func, PRECONDITIONS_MARKER)
@@ -520,9 +528,18 @@ class KeaTestRunner(TextTestRunner):
                     _widgets = func(self.options.Driver.getStaticChecker())
                     if not isinstance(_widgets, list):
                         _widgets = [_widgets]
-                    blocked_widgets.extend([
-                        w._getXPath(w.selector) for w in _widgets
-                    ])
+                    for w in _widgets:
+                        if isinstance(w, StaticU2UiObject):
+                            blocked_widgets.append(w._getXPath(w.selector))
+                        elif isinstance(w, u2.xpath.XPathSelector):
+                            def getXPathRepr(w):
+                                return w._parent.xpath
+                            blocked_widgets.append(getXPathRepr(w))
+                        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

kea2/kea_launcher.py

@@ -1,9 +1,10 @@
+import sys
 import argparse
-from typing import List
 import unittest
+from typing import List
 
 def _set_driver_parser(subparsers: "argparse._SubParsersAction[argparse.ArgumentParser]"):
-    parser = subparsers.add_parser("driver", help="Driver Settings")
+    parser = subparsers.add_parser("run", help="run kea2")
     parser.add_argument(
         "-s",
         "--serial",
@@ -96,21 +97,28 @@ def parse_args(argv: List):
     subparsers = parser.add_subparsers(dest="command", required=True)
 
     _set_driver_parser(subparsers)
-    if len(argv) == 0:
-        argv.append("-h")
     args = parser.parse_args(argv)
-    driver_info_logger(args)
-    unittest_info_logger(args)
     return args
 
-def run(argv=None):
-    import sys
-    if argv is None:
-        argv = sys.argv
-    args = parse_args(argv[1:])
+def _sanitize_args(args):
+    if args.agent == "u2" and not args.driver_name:
+        if args.extra == []:
+            args.driver_name = "d"
+        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:])
+
+    _sanitize_args(args)
+
+    driver_info_logger(args)
+    unittest_info_logger(args)
 
     from kea2 import KeaTestRunner, Options
     from kea2.u2Driver import U2Driver
+    U2Driver.setDeviceSerial(args.serial)
     options = Options(
         agent=args.agent,
         driverName=args.driver_name,

kea2/u2Driver.py

@@ -85,7 +85,8 @@ class StaticU2UiObject(u2.UiObject):
 
     def _transferU2Keys(self, originKey):
         filterDict = {
-            "resourceId": "resource-id"
+            "resourceId": "resource-id",
+            "description": "content-desc"
         }
         if filterDict.get(originKey, None):
             return filterDict[originKey]
@@ -116,7 +117,7 @@ class StaticU2UiObject(u2.UiObject):
 
     @property
     def exists(self):
-        self.selector["covered"] = "true"
+        dict.update(self.selector, {"covered": "true"})
         xpath = self._getXPath(self.selector)
         matched_widgets = self.session.xml.xpath(xpath)
         return bool(matched_widgets)
@@ -124,7 +125,7 @@ class StaticU2UiObject(u2.UiObject):
     def __len__(self):
         xpath = self._getXPath(self.selector)
         matched_widgets = self.session.xml.xpath(xpath)
-        return len(matched_widgets)   
+        return len(matched_widgets)
 
 
 def _get_bounds(raw_bounds):
@@ -216,12 +217,21 @@ class U2StaticDevice(u2.Device):
         def get_page_source(self):
             # print("[Debug] Using static get_page_source method")
             return u2.xpath.PageSource.parse(self._d.xml_raw)
-        xpathEntry = u2.xpath.XPathEntry(self)
+        xpathEntry = _XPathEntry(self)
         xpathEntry.get_page_source = types.MethodType(
             get_page_source, xpathEntry
         )
         return xpathEntry
 
+class _XPathEntry(u2.xpath.XPathEntry):
+    def __init__(self, d):
+        self.xpath = None
+        super().__init__(d)
+        
+    def __call__(self, xpath, source = None):
+        self.xpath = xpath
+        return super().__call__(xpath, source)
+
 
 class U2StaticChecker(AbstractStaticChecker):
     """

{kea2_python-0.0.1a0.dist-info → kea2_python-0.0.1a2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: Kea2-python
-Version: 0.0.1a0
+Version: 0.0.1a2
 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.9
@@ -48,59 +48,20 @@ In the future, Kea2 will be extended to support
 
 > Kea2 is inspired by many valuable insights, advices and lessons shared by experienced industrial practitioners from Bytedance (Zhao Zhang, Yuhui Su from the Fastbot team), OPay (Tiesong Liu), WeChat (Haochuan Lu), Huawei, Xiaomi and etc. Kudos!
 
-
-# Deploy Kea2
-
 ## Installation
 
 Running requirements/environment:
 - support Windows, MacOS and Linux
-- python 3.8+
+- python 3.9+
 - Android SDK installed
 - **VPN closed** (Features 2 and 3 required)
 
-1. Clone `Kea2` into your workspace.
-
-```bash
-git clone git@github.com:ecnusse/Kea2.git
-cd Kea2
-```
-
-2. Setup the python virtual environment with `uv`.
-
-> [uv](https://github.com/astral-sh/uv) is a extremely fast python package and project manager. We use `uv` to create a python virtual environment for Kea2 to avoid any dependency issues or conflicts with your existing python environment.
-`uv` is similar to `virtualenv` but much more powerful.
-Of course, you can also setup Kea2 in your [global environment](https://github.com/ecnusse/Kea2/tree/dev?tab=readme-ov-file#appendix-install-kea2-in-a-global-environment).
-
 ```bash
-pip install --upgrade pip
-pip install uv
-uv sync
-```
+python3 -m pip install Kea2-python
 
-> MacOS users may have trouble with global pip install. In such cases, they can use `brew`.
-```bash
-# For macOS users
-brew install uv
-uv sync
+kea2 -h
 ```
 
-3. Activate virtual environment
-
-- Linux and macOS
-```bash
-source .venv/bin/activate
-```
-
-- Windows cmd
-```cmd
-\.venv\Scripts\activate.bat
-```
-
-- Windows powershell
-```powershell
-\.venv\Scripts\activate.ps1
-```
 
 ## Quick Test
 
@@ -111,7 +72,8 @@ Kea2 connects to and runs on Android devices. We recommend you to do a quick tes
 2. Run `quickstart.py` to test a sample app `omninotes` (released as `omninotes.apk` in Kea2's repository). The script `quickstart.py` will automatically install and test this sample app for a short time.
 
 ```python
-python3 quickstart.py
+kea2 init
+python3 quickstart.py native
 ```
 
 If you can see the app `omninotes` is successfully running and tested, Kea2 works. Otherwise, please help [file a bug report](https://github.com/ecnusse/Kea2/issues) with the error message to us. Thank you!
@@ -133,7 +95,7 @@ Test your app with the full capability of [Fastbot](https://github.com/bytedance
 
 
 ```bash
-python3 kea_launcher.py driver -s "emulator-5554" -p it.feio.android.omninotes.alpha --agent native --running-minutes 10 --throttle 200
+kea2 run -s "emulator-5554" -p it.feio.android.omninotes.alpha --agent native --running-minutes 10 --throttle 200
 ```
 
 The usage is similar to the the original [Fastbot](https://github.com/bytedance/Fastbot_Android?tab=readme-ov-file#run-fastbot-with-shell-command)'s shell commands. 
@@ -185,19 +147,17 @@ In this case, the `Home` page is the entry page of the `Privacy` page and the `H
 - In script's test method `test_goToPrivacy`, we specify the interaction logic (i.e., opening `Drawer`, clicking the option `Setting` and clicking `Privacy`) to guide Fastbot to reach the `Privacy` page.
 - By the decorator `@prob`, we specify the probability (50% in this example) to do the guidance when we are at the `Home` page. As a result, Kea2 still allows Fastbot to explore other pages.
 
-You can find the full example in script `quickstart2.py` and run it by executing:
+You can find the full example in script `quickstart.py` and run it by executing:
 
+```python
+python3 quickstart.py u2
+```
 
 ```bash
-# Launch Kea2 and load one single script quickstart2.py.
-python3 kea_launcher.py driver -s "emulator-5554" -p it.feio.android.omninotes.alpha --agent u2 --running-minutes 10 --throttle 200 --driver-name d unittest quickstart2.py
+# Launch Kea2 and load one single script quickstart.py.
+kea2 run -s "emulator-5554" -p it.feio.android.omninotes.alpha --agent u2 --running-minutes 10 --throttle 200 --driver-name d unittest quickstart.py
 ```
 
-or simply run:
-
-```python
-python3 quickstart2.py
-```
 
 
 
@@ -294,21 +254,21 @@ We offer two ways to launch Kea2.
 
 ### 1. Launch by shell commands
 
-Kea2 is compatible with `unittest` framework. You can manage your test cases in unittest style. You can launch Kea2 with `kea_launcher.py` with two sub-commands `driver` (for Kea2 options) and `unittest` (for unittest options).
+Kea2 is compatible with `unittest` framework. You can manage your test cases in unittest style. You can launch Kea2 with `kea run` with driver options and sub-command `unittest` (for unittest options).
 
 The shell command:
 ```
-python3 kea_launcher.py driver <Kea2 cmds> unittest <unittest cmds> 
+kea2 run <Kea2 cmds> unittest <unittest cmds> 
 ```
 
 Sample shell commands:
 
 ```bash
 # Launch Kea2 and load one single script quickstart.py.
-python3 kea_launcher.py driver -s "emulator-5554" -p it.feio.android.omninotes.alpha --agent u2 --running-minutes 10 --throttle 200 --driver-name d unittest quickstart.py
+kea2 run -s "emulator-5554" -p it.feio.android.omninotes.alpha --agent u2 --running-minutes 10 --throttle 200 --driver-name d unittest quickstart.py
 
 # Launch Kea2 and load multiple scripts from the directory mytests/omni_notes
-python3 kea_launcher.py driver -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
+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 |

{kea2_python-0.0.1a0.dist-info → kea2_python-0.0.1a2.dist-info}/RECORD

@@ -1,16 +1,16 @@
 kea2/__init__.py,sha256=_IFDiyzb6OLyhjldBXrAol6OpOijTnJ2LYWMK4TqSno,121
 kea2/absDriver.py,sha256=1vXTkPqhhIosT8KpS6pwi7XKjNZTOuSb7mczhS_tMoQ,648
 kea2/adbUtils.py,sha256=IV-5G_3mc89YP1NJZJIWUrgxb13QECGGXTTANkGH_Rk,8986
-kea2/cli.py,sha256=MBNvw7utLfkAwFtoF3zbh7o44TBOrsWS0RF6EY0c9Do,4232
-kea2/keaUtils.py,sha256=pg6wsPaUf8BL91503bXm672DdYFoyi6NvgGNIASsblA,18718
-kea2/kea_launcher.py,sha256=phBIrtO8RIKhIXiaffIkoHMlU4QIt-pIEVxJ2Pn3nrk,3665
+kea2/cli.py,sha256=yTBmWUKi0onIWATV5uccwnItySwxFFUtewOiBEjQZAs,4466
+kea2/keaUtils.py,sha256=KF00-qf_R8-hk221uKJJi64TdOOKnSINeQrVWKzCN3Y,19452
+kea2/kea_launcher.py,sha256=pBjV3Hxv3Sh9MXiV50Afahcb3ebgoY0JQhRTCekOMRU,3916
 kea2/logWatcher.py,sha256=hd8banPiCa6aCQ6d_MznWKOdzK_A2X_dPbrx-usjxgE,1927
-kea2/u2Driver.py,sha256=Uyj0C2DFUCI1LB07YJHtLfvTsU_aaMtjhiweAVZ3uAw,9896
+kea2/u2Driver.py,sha256=dfvSapHL9LMyiSlFUCZMNI-G5usapqzGvaFu_lWv-s0,10193
 kea2/utils.py,sha256=zjuoVwts2qVX9GnTaPoiqarfcSvyfW6cAD3ESf_dmrQ,1284
 kea2/assets/fastbot-thirdpart.jar,sha256=0SZ_OoZFWDGMnazgXKceHgKvXdUDoIa3Gb2bcifaikk,85664
 kea2/assets/framework.jar,sha256=rTluOJJKj2DFwh7ascXso1udYdWv00BxBwSQ3Vmv-fw,1149240
-kea2/assets/monkeyq.jar,sha256=k1r0Rf4UPgA1tndCx0YEFL_5d6jY3W8hgi-rn8FdFVw,459851
-kea2/assets/quickstart.py,sha256=YsZCqLCwb5Mg8m0ybdyL-_TJ8FX2oKLyHZFJrk7fvkQ,2865
+kea2/assets/monkeyq.jar,sha256=TjszvflvE59ev9RhVhkfS_0L46VYZbL2wvpKRyA8ZMk,460366
+kea2/assets/quickstart.py,sha256=UeX_SIi_iEN9lzqit7dR1vSxA57fQ9ioCsBOSfzmkCY,3012
 kea2/assets/u2.jar,sha256=G9fFf-AZ0CdaZrk27V1-pfJE2Y5eO6PRzPShTnIe-U8,3746525
 kea2/assets/fastbot_configs/ADBKeyBoard.apk,sha256=L3Kva4gCQALo10EzinCvHrIbffGE3p94qSNbnS8CxP0,163634
 kea2/assets/fastbot_configs/abl.strings,sha256=Rn8_YEbVGOJqndIY_-kWnR5NaoFI-cuB-ij10Ddhl90,75
@@ -20,14 +20,14 @@ kea2/assets/fastbot_configs/max.fuzzing.strings,sha256=_3bNHwgzlISgxB7RmMury5X3q
 kea2/assets/fastbot_configs/max.schema.strings,sha256=zYupzvmTtnbPYomI2UCPk0s6PE97t94myZU_j3HutRM,40
 kea2/assets/fastbot_configs/max.strings,sha256=k82GAAZZG7KbDI7bk7DUklp41WJJO7j-j8Ss1BcybUw,32
 kea2/assets/fastbot_configs/max.tree.pruning,sha256=dm0oesN75FFbVSkV7STDUmrNMpQUBEuO7Uymt6nEkBc,629
-kea2/assets/fastbot_configs/widget.block.py,sha256=hj5xT1SpIqwVv-Dtww8Povrxi5MY0gD9kX_orQrWSjc,647
+kea2/assets/fastbot_configs/widget.block.py,sha256=xNlC3UwKgff3Cevg6dvzeu8nfEhhVm8CtvwLjsOkuXk,505
 kea2/assets/fastbot_libs/arm64-v8a/libfastbot_native.so,sha256=dA2Tf74-gDrCFdeClsf7qZAy0RqDZQOLlBZ-FViuorw,2005832
 kea2/assets/fastbot_libs/armeabi-v7a/libfastbot_native.so,sha256=GWcL8M8WfQAd9CfOM6pRYbOnxeycN-LiL7Mf59YIadE,1334420
 kea2/assets/fastbot_libs/x86/libfastbot_native.so,sha256=k-aw1gEXRWMKZRNHIggKNuZy0wC1y2BnveJGEIO6rbo,2036856
 kea2/assets/fastbot_libs/x86_64/libfastbot_native.so,sha256=tiofhlf4uMQcU5WAvrdLgTBME0lb83hVUoGtTwxmE8A,2121416
-kea2_python-0.0.1a0.dist-info/licenses/LICENSE,sha256=nM9PPjcsXVo5SzNsjRqWgA-gdJlwqZZcRDSC6Qf6bVE,2034
-kea2_python-0.0.1a0.dist-info/METADATA,sha256=Z6AWldJv7WwDnR3ybfaIhRFnYZedbP8Yd8u5KGLAyLo,20168
-kea2_python-0.0.1a0.dist-info/WHEEL,sha256=Nw36Djuh_5VDukK0H78QzOX-_FQEo6V37m3nkm96gtU,91
-kea2_python-0.0.1a0.dist-info/entry_points.txt,sha256=mFX06TyxXiUAJQ6JZn8QHzfn8n5R8_KJ5W-pTm_fRCA,39
-kea2_python-0.0.1a0.dist-info/top_level.txt,sha256=TsgNH4PQoNOVhegpO7AcjutMVWp6Z4KDL1pBH9FnMmk,5
-kea2_python-0.0.1a0.dist-info/RECORD,,
+kea2_python-0.0.1a2.dist-info/licenses/LICENSE,sha256=nM9PPjcsXVo5SzNsjRqWgA-gdJlwqZZcRDSC6Qf6bVE,2034
+kea2_python-0.0.1a2.dist-info/METADATA,sha256=q4kT2cBZftSN2DmR966S-YvswbBuwJq6yX9j_ELrK2c,19032
+kea2_python-0.0.1a2.dist-info/WHEEL,sha256=zaaOINJESkSfm_4HQVc5ssNzHCPXhJm0kEUakpsEHaU,91
+kea2_python-0.0.1a2.dist-info/entry_points.txt,sha256=mFX06TyxXiUAJQ6JZn8QHzfn8n5R8_KJ5W-pTm_fRCA,39
+kea2_python-0.0.1a2.dist-info/top_level.txt,sha256=TsgNH4PQoNOVhegpO7AcjutMVWp6Z4KDL1pBH9FnMmk,5
+kea2_python-0.0.1a2.dist-info/RECORD,,

{kea2_python-0.0.1a0.dist-info → kea2_python-0.0.1a2.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (80.7.1)
+Generator: setuptools (80.8.0)
 Root-Is-Purelib: true
 Tag: py3-none-any