Kea2-python 0.3.0__py3-none-any.whl → 0.3.2__py3-none-any.whl

kea2/u2Driver.py

@@ -1,12 +1,14 @@
+import functools
 import random
 import socket
+import time
 from time import sleep
 import uiautomator2 as u2
 import adbutils
 import types
 import rtree
 import re
-from typing import Any, Dict, List, Union
+from typing import Any, Dict, List, Union, Optional
 from http.client import HTTPResponse
 from lxml import etree
 from .absDriver import AbstractScriptDriver, AbstractStaticChecker, AbstractDriver
@@ -205,6 +207,122 @@ class StaticU2UiObject(u2.UiObject):
     def __getattr__(self, attr):
         return getattr(super(), attr)
 
+"""
+The definition of XpathStaticChecker
+"""
+class StaticXpathUiObject(u2.xpath.XPathSelector):
+    def __init__(self, session, selector):
+        self.session: U2StaticDevice = session
+        self.selector = selector
+
+    @property
+    def exists(self):
+        source = self.session.get_page_source()
+        return len(self.selector.all(source)) > 0
+
+    def __and__(self, value) -> 'StaticXpathUiObjectr':
+        s = u2.xpath.XPathSelector(self.selector)
+        s._next_xpath = u2.xpath.XPathSelector.create(value.selector)
+        s._operator = u2.xpath.Operator.AND
+        s._parent = self.selector._parent
+        self.selector = s
+        return self
+
+    def __or__(self, value) -> 'StaticXpathUiObject':
+        s = u2.xpath.XPathSelector(self.selector)
+        s._next_xpath = u2.xpath.XPathSelector.create(value.selector)
+        s._operator = u2.xpath.Operator.OR
+        s._parent = self.selector._parent
+        self.selector = s
+        return self
+
+    def selector_to_xpath(self, selector: u2.xpath.XPathSelector) -> str:
+        """
+            Convert an XPathSelector to a standard XPath expression.
+
+            Args:
+                selector: The XPathSelector object to convert.
+
+            Returns:
+                A standard XPath expression as a string.
+            """
+
+        def _handle_path(path):
+            if isinstance(path, u2.xpath.XPathSelector):
+                return self.selector_to_xpath(path)
+            elif isinstance(path, u2.xpath.XPath):
+                return str(path)
+            else:
+                return path
+
+        base_xpath = _handle_path(selector._base_xpath)
+        base_xpath = base_xpath.replace('//*', './/node')
+
+        if selector._operator is None:
+            return base_xpath
+        else:
+            print("Unsupported operator: {}".format(selector._operator))
+            return "//error"
+
+    def xpath(self, _xpath: Union[list, tuple, str]) -> 'StaticXpathUiObject':
+        """
+        add xpath to condition list
+        the element should match all conditions
+
+        Deprecated, using a & b instead
+        """
+        if isinstance(_xpath, (list, tuple)):
+            self.selector = functools.reduce(lambda a, b: a & b, _xpath, self)
+        else:
+            self.selector = self.selector & _xpath
+        return self
+
+    def child(self, _xpath: str) -> "StaticXpathUiObject":
+        """
+        add child xpath
+        """
+        if self.selector._operator or not isinstance(self.selector._base_xpath, u2.xpath.XPath):
+            raise u2.xpath.XPathError("can't use child when base is not XPath or operator is set")
+        new = self.selector.copy()
+        new._base_xpath = self.selector._base_xpath.joinpath(_xpath)
+        self.selector = new
+        return self
+
+    def get(self, timeout=None) -> "XMLElement":
+        """
+        Get first matched element
+
+        Args:
+            timeout (float): max seconds to wait
+
+        Returns:
+            XMLElement
+
+        """
+        if not self.exists:
+            return None
+        return self.get_last_match()
+
+    def get_last_match(self) -> "u2.xpath.XMLElement":
+        return self.selector.all(self.selector._last_source)[0]
+
+    def parent_exists(self, xpath: Optional[str] = None):
+        el = self.get()
+        if el is None:
+            return False
+        element = el.parent(xpath) if hasattr(el, 'parent') else None
+        return True if element is not None else False
+
+    def __getattr__(self, key: str):
+        """
+              In IPython console, attr:_ipython_canary_method_should_not_exist_ will be called
+              So here ignore all attr startswith _
+              """
+        if key.startswith("_"):
+            raise AttributeError("Invalid attr", key)
+        if not hasattr(u2.xpath.XMLElement, key):
+            raise AttributeError("Invalid attr", key)
+        return getattr(super(), key)
 
 def _get_bounds(raw_bounds):
     pattern = re.compile(r"\[(-?\d+),(-?\d+)\]\[(-?\d+),(-?\d+)\]")
@@ -299,7 +417,8 @@ class U2StaticDevice(u2.Device):
     def xpath(self) -> u2.xpath.XPathEntry:
         def get_page_source(self):
             # print("[Debug] Using static get_page_source method")
-            return u2.xpath.PageSource.parse(self._d.xml_raw)
+            xml_raw = etree.tostring(self._d.xml, encoding='unicode')
+            return u2.xpath.PageSource.parse(xml_raw)
         xpathEntry = _XPathEntry(self)
         xpathEntry.get_page_source = types.MethodType(
             get_page_source, xpathEntry
@@ -316,10 +435,14 @@ class _XPathEntry(u2.xpath.XPathEntry):
         self.xpath = None
         super().__init__(d)
         
-    def __call__(self, xpath, source = None):
+    # def __call__(self, xpath, source = None):
         # TODO fully support xpath in widget.block.py
-        self.xpath = xpath
-        return super().__call__(xpath, source)
+        # self.xpath = xpath
+        # return super().__call__(xpath, source)
+    def __call__(self, xpath, source=None):
+        ui = StaticXpathUiObject(session=self, selector=u2.xpath.XPathSelector(xpath, source=source))
+        return ui
+
 
 
 class U2StaticChecker(AbstractStaticChecker):

kea2/utils.py

@@ -1,6 +1,7 @@
 import logging
 import os
 from pathlib import Path
+import traceback
 from typing import TYPE_CHECKING
 
 import time
@@ -26,6 +27,9 @@ def getLogger(name: str) -> logging.Logger:
     return logger
 
 
+logger = getLogger(__name__)
+
+
 def singleton(cls):
     _instance = {}
 
@@ -60,12 +64,49 @@ def getProjectRoot():
     return cur_dir
 
 
-def timer(func):
-    @wraps(func)
-    def wrapper(*args, **kwargs):
-        start_time = time.time()
-        result = func(*args, **kwargs)
-        end_time = time.time()
-        print(f"Function '{func.__name__}' executed in {(end_time - start_time):.4f} seconds.")
-        return result
-    return wrapper
+def timer(log_info: str=None):
+    """ ### Decorator to measure the execution time of a function.
+
+    This decorator can be used to wrap functions where you want to log the time taken for execution
+    
+    ### Usage:
+        - @timer("Function execution took %cost_time seconds.")
+        - @timer()  # If no log_info is provided, it will print the function name and execution time.
+    
+    `%cost_time` will be replaced with the actual time taken for execution.
+    """
+    def accept(func):
+        @wraps(func)
+        def wrapper(*args, **kwargs):
+            start_time = time.time()
+            result = func(*args, **kwargs)
+            end_time = time.time()
+            if log_info:
+                logger.info(log_info.replace(r"%cost_time", f"{end_time - start_time:.4f}"))
+            else:
+                logger.info(f"Function '{func.__name__}' executed in {(end_time - start_time):.4f} seconds.")
+            return result
+        return wrapper
+    return accept
+
+
+def catchException(log_info: str):
+    """ ### Decorator to catch exceptions and print log info.
+
+    This decorator can be used to wrap functions that may raise exceptions,
+    allowing you to log a message when the exception is raised.
+
+    ### Usage:
+        - @catchException("An error occurred in the function ****.")
+    """
+    def accept(func):
+        @wraps(func)
+        def wrapper(*args, **kwargs):
+            try:
+                return func(*args, **kwargs)
+            except Exception as e:
+                logger.info(log_info)
+                tb = traceback.format_exception(type(e), e, e.__traceback__.tb_next)
+                print(''.join(tb), end='', flush=True)
+        return wrapper
+    return accept

{kea2_python-0.3.0.dist-info → kea2_python-0.3.2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: Kea2-python
-Version: 0.3.0
+Version: 0.3.2
 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
@@ -10,6 +10,7 @@ Requires-Dist: rtree>=1.3.0
 Requires-Dist: jinja2>=3.0.0
 Requires-Dist: uiautomator2>=3.3.3
 Requires-Dist: adbutils>=2.9.3
+Requires-Dist: setuptools>=75.3.2
 Dynamic: license-file
 
 
@@ -17,6 +18,7 @@ Dynamic: license-file
 [![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)
+[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/ecnusse/Kea2)
 
 <div>
     <img src="https://github.com/user-attachments/assets/84e47b87-2dd2-4d7e-91d1-e8c1d1db0cf4" style="border-radius: 14px; width: 20%; height: 20%;"/> 
@@ -31,6 +33,13 @@ The group has reached its capacity. Please contact Xixian Liang at [xixian@stu.e
 
 ## About 
 
+<div align="center">
+    <img src="docs/images/kea2_logo.png" alt="kea_logo" style="border-radius: 14px; width: 20%; height: 20%;"/>
+</div>
+<div align="center">
+    <a href="https://en.wikipedia.org/wiki/Kea">Kea2's logo: A large parrot skilled in finding "bugs"</a>
+</div>
+
 Kea2 is an easy-to-use tool for fuzzing mobile apps. Its key *novelty* is able to fuse automated UI testing with scripts (usually written by human), thus empowering automated UI testing with human intelligence for effectively finding *crashing bugs* as well as *non-crashing functional (logic) bugs*. 
 
 Kea2 is currently built on top of [Fastbot](https://github.com/bytedance/Fastbot_Android), *an industrial-strength automated UI testing tool*, and [uiautomator2](https://github.com/openatx/uiautomator2), *an easy-to-use and stable Android automation library*.
@@ -40,7 +49,7 @@ Kea2 currently targets [Android](https://en.wikipedia.org/wiki/Android_(operatin
 
 <div align="center">
     <div style="max-width:80%; max-height:80%">
-    <img src="docs/intro.png" style="border-radius: 14px; width: 80%; height: 80%;"/> 
+    <img src="docs/images/intro.png" style="border-radius: 14px; width: 80%; height: 80%;"/> 
     </div>
 </div>
 
@@ -60,11 +69,17 @@ Kea2 currently targets [Android](https://en.wikipedia.org/wiki/Android_(operatin
 | **Finding crashes in deep states** |  | :+1: | :+1: |
 | **Finding non-crashing functional (logic) bugs** |  |  | :+1: |
 
-## Kea2's Known Users
+## Kea2's Users
+
+Kea2 (and its idea) has been used/integrated by
 
-[OPay Business](https://play.google.com/store/apps/details?id=team.opay.pay.merchant.service) --- a financial & payment app
+- [OPay Business](https://play.google.com/store/apps/details?id=team.opay.pay.merchant.service) --- a financial & payment app. OPay uses Kea2 for regression testing on POS machines and mobile devices.
 
-We are glad to hear if you are using Kea2 for your app.
+- [WeChat's iExplorer]() --- WeChat's in-house testing platform
+
+- [ByteDance's Fastbot](https://github.com/bytedance/Fastbot_Android)
+
+Please let us know and willing to hear your feedback/questions if you are also using Kea2.
 
 ## Design & Roadmap
 Kea2 currently works with:
@@ -82,7 +97,7 @@ In the future, Kea2 will be extended to support
 
 Running environment:
 - support Windows, MacOS and Linux
-- python 3.8+, Android 5.0+ (Android SDK installed)
+- python 3.8+, Android 5.0~16.0 (Android SDK installed)
 - **VPN closed** (Features 2 and 3 required)
 
 Install Kea2 by `pip`:
@@ -193,7 +208,7 @@ In Feature 3, a script is composed of three elements:
 In a social media app, message sending is a common feature. On the message sending page, the `send` button should always appears when the input box is not empty (i.e., has some message).
 
 <div align="center">
-    <img src="docs/socialAppBug.png" style="border-radius: 14px; width:30%; height:40%;"/>
+    <img src="docs/images/socialAppBug.png" style="border-radius: 14px; width:30%; height:40%;"/>
 </div>
 
 <div align="center">
@@ -230,7 +245,55 @@ You can find the [user manual](docs/manual_en.md), which includes:
 - How to run Kea2 and Kea2's command line options
 - How to find and understand Kea2's testing results
 - How to [whitelist or blacklist](docs/blacklisting.md) specific activities, UI widgets and UI regions during fuzzing
-- [Common Q&A for PBT and Kea2](https://sy8pzmhmun.feishu.cn/wiki/SLGwwqgzIiEuC3kwmV8cSZY0nTg?from=from_copylink)
+- [Q&A for Kea2 and PBT (对Kea2和PBT技术的常见问题和回答)](https://sy8pzmhmun.feishu.cn/wiki/SLGwwqgzIiEuC3kwmV8cSZY0nTg?from=from_copylink) 
+
+Some blogs on Kea/Kea2 (in Chinese):
+- [别再苦哈哈写测试脚本了，生成它们吧！(一)](https://mp.weixin.qq.com/s/R2kLCkXpDjpa8wCX4Eidtg)
+- [别再苦哈哈写测试脚本了，生成它们吧！(二)](https://mp.weixin.qq.com/s/s4WkdstNcKupu9OP8jeOXw)
+- [别再苦哈哈写测试脚本了，生成它们吧！(三)](https://mp.weixin.qq.com/s/BjXyo-xJRmPB_sCc4pmh8g)
+- [2025 Let’s GoSSIP 软件安全暑期学校预告第一弹——Kea2](https://mp.weixin.qq.com/s/8_0_GNNin8E5BqTbJU33wg)
+- [功能性质驱动的测试技术：下一代GUI自动化测试技术](https://appw8oh6ysg4044.xet.citv.cn/p/course/video/v_6882fa14e4b0694ca0ec0a1b) --- 视频回放&PPT@MTSC 2025
+
+工业界对Kea2的理解和评价（点击箭头查看详情）：
+
+<details>
+  <summary>Kea2的性质是什么含义？Kea2意义和价值是什么？</summary>
+
+    kea2 其实是一个工具，它是python+u2+fastbot的集合体。 它本身更像是一台装好了发动机和轮子的汽车底盘。
+
+    性质是苏老师他们团队提出的一个概念， 转换到测试领域的实际工作中，性质对应的是最小单位的功能（原子级功能），性质的依赖条件很少或没有，它可以自身运行。一个典型的性质就是登录，它仅仅具有输入用户名，输入密码，提交。再举个例子，给视频点个赞，也就是简单的两三步。就是一个性质。
+
+    性质与kea2结合的意义是在于解决过去使用appium过重的问题。用appium去测试一个性质通常要写很多行的代码，引导界面到达性质的位置。但使用kea2，就只需要编写性质，如何到其所在的位置是交给fastbot和它的学习算法来搞定的。 
+
+    kea2另个重大的价值是，它解决了上述思想所需要的技术支撑，比appium更轻量的UI编写方式，fastbot编写性质的能力不足，以及无法编写逻辑和断言。整体上是保留了fastbot以往的优秀品质，完善了其不足和短板。
+
+    简而言之，需要做传统的编排型的功能测试，仍然使用appium，使用kea2也行，但你感觉不到它的价值。本身有需要做混沌测试，模糊测试，兼容性测试。那么强烈，强烈推荐kea2。kea2更偏探索性测试而非编排型。
+</details>
+
+<details>
+  <summary>kea2组成是什么？kea2的核心作用？kea2做了什么？</summary>
+
+kea2 组成：
+
+    fastbot  --  fuzz测试引擎，负责跑路。
+    u2 -- 负责进行业务空间的操作。与使用selenium，appium，没什么区别。
+    python --  u2的操作，逻辑的编写，定制化的实现。
+
+kea2的核心作用：
+
+    提供了条件触发器。 在FB跑路的时候，会不停遍历条件触发器，一旦触发，挂起FB，开始执行触发器指定的 ui test 及 assert。执行完毕，继续切回FB跑路。
+
+hea2做了什么：
+
+    替换了FB的条件触发功能。
+    替换了FB的黑名单，黑控件功能。
+    替换了FB剪枝功能。
+    增加了多元化的元素空间操作能力。
+    增加了fuzz测试中的 逻辑设定。
+    增加了断言能力。
+    增加了元素操作能力。
+</details>
+
 
 ## Open-source projects used by Kea2
 

{kea2_python-0.3.0.dist-info → kea2_python-0.3.2.dist-info}/RECORD

@@ -1,16 +1,16 @@
 kea2/__init__.py,sha256=JFJjqgf5KB4bXUFQ3upkEug0cFMFIk9p3OHV9vzulHw,75
 kea2/absDriver.py,sha256=NzmsLs1Ojz-yEXctGAqj7aKBwAQW19zd83l65RABCe8,1288
 kea2/adbUtils.py,sha256=zi0T0_g44xZQZe3XYzBsuh7VTHpdZ4dd6yKi-p7BTYI,19939
-kea2/bug_report_generator.py,sha256=eorBNJKJ4TgM5cL1_QLOGPgfISvbRIUb8ns87gjD9IM,43050
+kea2/bug_report_generator.py,sha256=qHwHupANp5-IZXlpSnYy5rkf07BXu2QvvfWZzJWtc6k,42590
 kea2/cli.py,sha256=MccJhY8VPZa1rMAbirm3dmbzDx1lf2w3zrpF1ZUq2m0,6481
-kea2/fastbotManager.py,sha256=gQ3FI1AezCxZ8NorOOW9_K6ASWpRTYTLpJ7eR1R4-8Y,7973
-kea2/keaUtils.py,sha256=UFZo6iT03sXL3tDoTCWza8RaqcVnTRjSqWdBMrc49Qc,25904
+kea2/fastbotManager.py,sha256=pGuAH-X26nOy2Qj6Hg5aoMxJx4KfsRk6bj6nhcPENGc,8158
+kea2/keaUtils.py,sha256=KRBYI6Vn36liKj8jFSH0W-ktGgHr-0VdC3xiX_mCF5E,25617
 kea2/kea_launcher.py,sha256=M9TMCdgkteCWO5iBxJRDRvb7dikanoPf3jdicCEurU8,6268
 kea2/logWatcher.py,sha256=Dp6OzvLSuWYw0AqdcPDqfotaRZQgpF8S49LInGsAWp8,2599
-kea2/report_merger.py,sha256=YOlxK20dsR2OU-LtyGzVrMH55j_wdfWhvTvq7ocARMc,23901
+kea2/report_merger.py,sha256=0b-g59pdrsJDwVNek02ouu1utuu_Sd_1oEMQa4e23xI,24884
 kea2/resultSyncer.py,sha256=9kb3H0Innwj7oPboDDTf97nbjam7EP6HYxywR9B8SvM,2437
-kea2/u2Driver.py,sha256=BZMQOQtYX2Oo6nXRPjIspRlc_TpPo_tgGo2fOLDYYMo,15614
-kea2/utils.py,sha256=QXaiUhOstcKyVl0TZOuVB8SaxVVK1lJGpWvhJ4ddWQY,1817
+kea2/u2Driver.py,sha256=SfHkUAp6uHHSllPZmKs7C8JaEGGuX9DPWgshiqyWI5k,19775
+kea2/utils.py,sha256=x0VTGweW-XShG9MuwZDMP13SBg8jQXYa7e0AXdwYX38,3270
 kea2/assets/fastbot-thirdpart.jar,sha256=0SZ_OoZFWDGMnazgXKceHgKvXdUDoIa3Gb2bcifaikk,85664
 kea2/assets/framework.jar,sha256=rTluOJJKj2DFwh7ascXso1udYdWv00BxBwSQ3Vmv-fw,1149240
 kea2/assets/kea2-thirdpart.jar,sha256=HYdtG2gqDLuLb72dpK3lX-Y6QUNTrJ-bfQopU5aWpfo,359346
@@ -28,11 +28,11 @@ kea2/assets/fastbot_libs/arm64-v8a/libfastbot_native.so,sha256=tAFrG73pJi7XakRxS
 kea2/assets/fastbot_libs/armeabi-v7a/libfastbot_native.so,sha256=UV8bhaiPoPKdd3q0vj3kSZqPR9anllai_tz_2QkMMbQ,1335372
 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/templates/bug_report_template.html,sha256=JPELW0QcDkWqabkkUqxRX6XXERKuNGVitML6ZRUKkJU,146879
-kea2/templates/merged_bug_report_template.html,sha256=mMq1Vavd_wCDvommpO4C5Z1Hejjn4WZre-KSDXD74LY,110298
-kea2_python-0.3.0.dist-info/licenses/LICENSE,sha256=nM9PPjcsXVo5SzNsjRqWgA-gdJlwqZZcRDSC6Qf6bVE,2034
-kea2_python-0.3.0.dist-info/METADATA,sha256=ZXOHCsDg7EPz3o-cuuzJ5nyMld_Nek1bfi4cGB0zKCI,14588
-kea2_python-0.3.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-kea2_python-0.3.0.dist-info/entry_points.txt,sha256=mFX06TyxXiUAJQ6JZn8QHzfn8n5R8_KJ5W-pTm_fRCA,39
-kea2_python-0.3.0.dist-info/top_level.txt,sha256=TsgNH4PQoNOVhegpO7AcjutMVWp6Z4KDL1pBH9FnMmk,5
-kea2_python-0.3.0.dist-info/RECORD,,
+kea2/templates/bug_report_template.html,sha256=XoLAqiPfk5asvSRhhI5nCity8Z77rxMBGT2_8rFrJP4,151729
+kea2/templates/merged_bug_report_template.html,sha256=awhMSURsP6Gpw0YHTs3xWZMQO7dhi0yM3H2JYHQ5_zA,135668
+kea2_python-0.3.2.dist-info/licenses/LICENSE,sha256=nM9PPjcsXVo5SzNsjRqWgA-gdJlwqZZcRDSC6Qf6bVE,2034
+kea2_python-0.3.2.dist-info/METADATA,sha256=dD3gescsC5Q-R8OZYFfvbiYBDhvJefFXzopffB2EPVI,18498
+kea2_python-0.3.2.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+kea2_python-0.3.2.dist-info/entry_points.txt,sha256=mFX06TyxXiUAJQ6JZn8QHzfn8n5R8_KJ5W-pTm_fRCA,39
+kea2_python-0.3.2.dist-info/top_level.txt,sha256=TsgNH4PQoNOVhegpO7AcjutMVWp6Z4KDL1pBH9FnMmk,5
+kea2_python-0.3.2.dist-info/RECORD,,