Kea2-python 0.1.2__py3-none-any.whl → 0.2.0__py3-none-any.whl

kea2/templates/bug_report_template.html

@@ -356,48 +356,7 @@
 
         <!-- Key Statistics -->
         <div class="row g-4 mb-4">
-            <div class="col-md-6">
-                <div class="stats-card">
-                    <div class="card-header bg-primary text-white">
-                        <i class="bi bi-stopwatch"></i> Time Statistics
-                    </div>
-                    <div class="card-body">
-                        <div class="mb-3">
-                            <h5 class="d-flex justify-content-between">
-                                <span>First Bug Discovery Time:</span>
-                                <span class="value-danger">{{ (first_bug_time / 60)|int }} min: {{ (first_bug_time % 60)|int }} sec</span>
-                            </h5>
-                            <div class="progress">
-                                <div class="progress-bar bg-danger" role="progressbar" 
-                                     style="width: calc({{ first_bug_time }} / {{ total_testing_time }} * 100%);" 
-                                     aria-valuenow="{{ first_bug_time }}" aria-valuemin="0" aria-valuemax="{{ total_testing_time }}"></div>
-                            </div>
-                        </div>
-                        <div class="mb-3">
-                            <h5 class="d-flex justify-content-between">
-                                <span>First Precondition Satisfaction Time:</span>
-                                <span class="value-success">{{ (first_precondition_time / 60)|int }} min: {{ (first_precondition_time % 60)|int }} sec</span>
-                            </h5>
-                            <div class="progress">
-                                <div class="progress-bar bg-success" role="progressbar" 
-                                     style="width: calc({{ first_precondition_time }} / {{ total_testing_time }} * 100%);" 
-                                     aria-valuenow="{{ first_precondition_time }}" aria-valuemin="0" aria-valuemax="{{ total_testing_time }}"></div>
-                            </div>
-                        </div>
-                        <div>
-                            <h5 class="d-flex justify-content-between">
-                                <span>Total Testing Time:</span>
-                                <span class="value-primary">{{ (total_testing_time / 60)|int }} min: {{ (total_testing_time % 60)|int }} sec</span>
-                            </h5>
-                            <div class="progress">
-                                <div class="progress-bar bg-primary" role="progressbar" style="width: 100%;" 
-                                     aria-valuenow="{{ total_testing_time }}" aria-valuemin="0" aria-valuemax="{{ total_testing_time }}"></div>
-                            </div>
-                        </div>
-                    </div>
-                </div>
-            </div>
-            <div class="col-md-6">
+            <div class="col-12">
                 <div class="stats-card">
                     <div class="card-header bg-success text-white">
                         <i class="bi bi-bar-chart"></i> Coverage Statistics
@@ -437,7 +396,7 @@
                 <!-- Tested Activities Panel -->
                 <div class="col-md-6">
                     <div class="card">
-                        <div class="card-header bg-success text-white">
+                        <div class="card-header bg-warning text-white">
                             <div class="d-flex justify-content-between align-items-center">
                                 <span><i class="bi bi-check-circle"></i> Tested Activities ({{ tested_activities|length }})</span>
                                 <span class="badge bg-light text-dark">{{ tested_activities|length }} / {{ total_activities_count }}</span>
@@ -605,14 +564,14 @@
                         </tr>
                     </thead>
                     <tbody id="property-stats-container">
-                        {% for stat in property_stats %}
+                        {% for property_name, test_result in property_stats.items() %}
                         <tr class="property-stat-row" data-page="1">
-                            <td>{{ stat.index }}</td>
-                            <td><span class="badge bg-light text-dark badge-custom">{{ stat.property_name }}</span></td>
-                            <td>{{ stat.precond_satisfied }}</td>
-                            <td>{{ stat.precond_checked }}</td>
-                            <td><span class="badge bg-danger text-white">{{ stat.postcond_violated }}</span></td>
-                            <td><span class="badge bg-warning text-dark">{{ stat.error }}</span></td>
+                            <td>{{ loop.index }}</td>
+                            <td><span class="badge bg-light text-dark badge-custom">{{ property_name }}</span></td>
+                            <td>{{ test_result.precond_satisfied|default(0) }}</td>
+                            <td>{{ test_result.executed|default(0) }}</td>
+                            <td><span class="badge bg-danger text-white">{{ test_result.fail|default(0) }}</span></td>
+                            <td><span class="badge bg-warning text-dark">{{ test_result.error|default(0) }}</span></td>
                         </tr>
                         {% endfor %}
                     </tbody>

kea2/u2Driver.py

@@ -1,10 +1,13 @@
 import random
 import socket
+from time import sleep
 import uiautomator2 as u2
+import adbutils
 import types
 import rtree
 import re
-from typing import Dict, List, Union
+from typing import Any, Dict, List, Union
+from http.client import HTTPResponse
 from lxml import etree
 from .absDriver import AbstractScriptDriver, AbstractStaticChecker, AbstractDriver
 from .adbUtils import list_forwards, remove_forward, create_forward
@@ -16,7 +19,7 @@ import logging
 logging.getLogger("urllib3").setLevel(logging.INFO)
 logging.getLogger("uiautomator2").setLevel(logging.INFO)
 
-logger = getLogger(__name__)
+logger = getLogger(__name__) 
 
 """
 The definition of U2ScriptDriver
@@ -35,34 +38,24 @@ class U2ScriptDriver(AbstractScriptDriver):
     """
 
     deviceSerial: str = None
+    transportId: str = None
     d = None
 
+    @classmethod
+    def setTransportId(cls, transportId):
+        cls.transportId = transportId
+
     @classmethod
     def setDeviceSerial(cls, deviceSerial):
         cls.deviceSerial = deviceSerial
 
     def getInstance(self):
         if self.d is None:
-            self.d = (
-                u2.connect() if self.deviceSerial is None
-                else u2.connect(self.deviceSerial)
-            )
-
-            def get_u2_forward_port() -> int:
-                """rewrite forward_port mothod to avoid the relocation of port
-                :return: the new forward port
-                """
-                print("Rewriting forward_port method", flush=True)
-                self.d._dev.forward_port = types.MethodType(
-                                forward_port, self.d._dev)
-                lport = self.d._dev.forward_port(8090)
-                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)
+            adb = adbutils.device(serial=self.deviceSerial, transport_id=self.transportId)
+            print("[INFO] Connecting to uiautomator2. Please wait ...")
+            self.d = u2.connect(adb)
+            sleep(5)
+            self.d._device_server_port = 8090
 
         return self.d
 
@@ -76,10 +69,11 @@ class U2ScriptDriver(AbstractScriptDriver):
                 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)
+        # logger.debug("U2Driver tearDown: stop_uiautomator")
+        # self.d.stop_uiautomator()
+        # logger.debug("U2Driver tearDown: remove forward")
+        # self._remove_remote_port(8090)
+        pass
 
 """
 The definition of U2StaticChecker
@@ -100,39 +94,105 @@ class StaticU2UiObject(u2.UiObject):
             return filterDict[originKey]
         return originKey
 
-    def _getXPath(self, kwargs: Dict[str, str]):
+    def selector_to_xpath(self, selector: u2.Selector, is_initial: bool = True) -> str:
+        """
+            Convert a u2 Selector into an XPath expression compatible with Java Android UI controls.
 
-        def filter_selectors(kwargs: Dict[str, str]):
-            """
-            filter the selector
-            """
-            new_kwargs = dict()
-            SPECIAL_KEY = {"mask", "childOrSibling", "childOrSiblingSelector"}
-            for key, val in kwargs.items():
-                if key in SPECIAL_KEY:
-                    continue
-                key = self._transferU2Keys(key)
-                new_kwargs[key] = val
-            return new_kwargs
+            Args:
+                selector (u2.Selector): A u2 Selector object
+                is_initial (bool): Whether it is the initial node, defaults to True
 
-        kwargs = filter_selectors(kwargs)
+            Returns:
+                str: The corresponding XPath expression
+            """
+        try:
 
-        attrLocs = [
-            f"[@{k}='{v}']" for k, v in kwargs.items()
-        ]
-        xpath = f".//node{''.join(attrLocs)}"
-        return xpath
+            xpath = ".//node" if is_initial else "node"
+
+            conditions = []
+
+            if "className" in selector:
+                conditions.insert(0, f"[@class='{selector['className']}']")
+
+            if "text" in selector:
+                conditions.append(f"[@text='{selector['text']}']")
+            elif "textContains" in selector:
+                conditions.append(f"[contains(@text, '{selector['textContains']}')]")
+            elif "textStartsWith" in selector:
+                conditions.append(f"[starts-with(@text, '{selector['textStartsWith']}')]")
+            elif "textMatches" in selector:
+                raise NotImplementedError("'textMatches' syntax is not supported")
+
+            if "description" in selector:
+                conditions.append(f"[@content-desc='{selector['description']}']")
+            elif "descriptionContains" in selector:
+                conditions.append(f"[contains(@content-desc, '{selector['descriptionContains']}')]")
+            elif "descriptionStartsWith" in selector:
+                conditions.append(f"[starts-with(@content-desc, '{selector['descriptionStartsWith']}')]")
+            elif "descriptionMatches" in selector:
+                raise NotImplementedError("'descriptionMatches' syntax is not supported")
+
+            if "packageName" in selector:
+                conditions.append(f"[@package='{selector['packageName']}']")
+            elif "packageNameMatches" in selector:
+                raise NotImplementedError("'packageNameMatches' syntax is not supported")
+
+            if "resourceId" in selector:
+                conditions.append(f"[@resource-id='{selector['resourceId']}']")
+            elif "resourceIdMatches" in selector:
+                raise NotImplementedError("'resourceIdMatches' syntax is not supported")
+
+            bool_props = ["checkable", "checked", "clickable", "longClickable", "scrollable", "enabled", "focusable",
+                          "focused", "selected", "covered"]
+
+            def str_to_bool(value):
+                """Convert string 'true'/'false' to boolean, or return original value if already boolean"""
+                if isinstance(value, str):
+                    return value.lower() == "true"
+                return bool(value)
+
+            for prop in bool_props:
+                if prop in selector:
+                    bool_value = str_to_bool(selector[prop])
+                    value = "true" if bool_value else "false"
+                    conditions.append(f"[@{prop}='{value}']")
+
+            if "index" in selector:
+                conditions.append(f"[@index='{selector['index']}']")
+
+            xpath += "".join(conditions)
+
+            if "childOrSibling" in selector and selector["childOrSibling"]:
+                for i, relation in enumerate(selector["childOrSibling"]):
+                    sub_selector = selector["childOrSiblingSelector"][i]
+                    sub_xpath = self.selector_to_xpath(sub_selector, False)
+
+                    if relation == "child":
+                        xpath += f"//{sub_xpath}"
+                    elif relation == "sibling":
+                        cur_root = xpath
+                        following_sibling = cur_root + f"/following-sibling::{sub_xpath}"
+                        preceding_sibling = cur_root + f"/preceding-sibling::{sub_xpath}"
+                        xpath = f"({following_sibling} | {preceding_sibling})"
+            if "instance" in selector:
+                xpath = f"({xpath})[{selector['instance'] + 1}]"
+
+            return xpath
+
+        except Exception as e:
+            print(f"Error occurred during selector conversion: {e}")
+            return "//error"
 
 
     @property
     def exists(self):
-        dict.update(self.selector, {"covered": "false"})
-        xpath = self._getXPath(self.selector)
+        set_covered_to_deepest_node(self.selector)
+        xpath = self.selector_to_xpath(self.selector)
         matched_widgets = self.session.xml.xpath(xpath)
         return bool(matched_widgets)
 
     def __len__(self):
-        xpath = self._getXPath(self.selector)
+        xpath = self.selector_to_xpath(self.selector)
         matched_widgets = self.session.xml.xpath(xpath)
         return len(matched_widgets)
     
@@ -142,6 +202,9 @@ class StaticU2UiObject(u2.UiObject):
     def sibling(self, **kwargs):
         return StaticU2UiObject(self.session, self.selector.clone().sibling(**kwargs))
 
+    def __getattr__(self, attr):
+        return getattr(super(), attr)
+
 
 def _get_bounds(raw_bounds):
     pattern = re.compile(r"\[(-?\d+),(-?\d+)\]\[(-?\d+),(-?\d+)\]")
@@ -227,7 +290,9 @@ class U2StaticDevice(u2.Device):
         self._script_driver = script_driver
 
     def __call__(self, **kwargs):
-        return StaticU2UiObject(session=self, selector=u2.Selector(**kwargs))
+        ui = StaticU2UiObject(session=self, selector=u2.Selector(**kwargs))
+        ui.jsonrpc = self._script_driver.jsonrpc
+        return ui
 
     @property
     def xpath(self) -> u2.xpath.XPathEntry:
@@ -274,7 +339,12 @@ class U2StaticChecker(AbstractStaticChecker):
     def setHierarchy(self, hierarchy: str):
         if hierarchy is None:
             return
-        self.d.xml = etree.fromstring(hierarchy.encode("utf-8"))
+        if isinstance(hierarchy, str):
+            self.d.xml = etree.fromstring(hierarchy.encode("utf-8"))
+        elif isinstance(hierarchy, etree._Element):
+            self.d.xml = hierarchy
+        elif isinstance(hierarchy, etree._ElementTree):
+            self.d.xml = hierarchy.getroot()
         _HindenWidgetFilter(self.d.xml)
 
     def getInstance(self, hierarchy: str=None):
@@ -290,8 +360,11 @@ class U2Driver(AbstractDriver):
     staticChecker = None
 
     @classmethod
-    def setDeviceSerial(cls, deviceSerial):
-        U2ScriptDriver.setDeviceSerial(deviceSerial)
+    def setDevice(cls, kwarg):
+        if kwarg.get("serial"):
+            U2ScriptDriver.setDeviceSerial(kwarg["serial"])
+        if kwarg.get("transport_id"):
+            U2ScriptDriver.setTransportId(kwarg["transport_id"])
 
     @classmethod
     def getScriptDriver(self):
@@ -324,96 +397,12 @@ def forward_port(self, remote: Union[int, str]) -> int:
                 and f.remote == remote
                 and f.local.startswith("tcp:")
             ):  # yapf: disable
-                return int(f.local[len("tcp:") :])
+                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
 
-
-def selector_to_xpath(selector: u2.Selector, is_initial: bool = True) -> str:
-    """
-    Convert a u2 Selector into an XPath expression compatible with Java Android UI controls.
-
-    Args:
-        selector (u2.Selector): A u2 Selector object
-        is_initial (bool): Whether it is the initial node, defaults to True
-
-    Returns:
-        str: The corresponding XPath expression
-    """
-    try:
-        if is_initial:
-            xpath = ".//node"
-        else:
-            xpath = "node"
-
-        conditions = []
-
-        if "className" in selector:
-            conditions.insert(0, f"[@class='{selector['className']}']")  # 将 className 条件放在前面
-
-        if "text" in selector:
-            conditions.append(f"[@text='{selector['text']}']")
-        elif "textContains" in selector:
-            conditions.append(f"[contains(@text, '{selector['textContains']}')]")
-        elif "textMatches" in selector:
-            conditions.append(f"[re:match(@text, '{selector['textMatches']}')]")
-        elif "textStartsWith" in selector:
-            conditions.append(f"[starts-with(@text, '{selector['textStartsWith']}')]")
-
-        if "description" in selector:
-            conditions.append(f"[@content-desc='{selector['description']}']")
-        elif "descriptionContains" in selector:
-            conditions.append(f"[contains(@content-desc, '{selector['descriptionContains']}')]")
-        elif "descriptionMatches" in selector:
-            conditions.append(f"[re:match(@content-desc, '{selector['descriptionMatches']}')]")
-        elif "descriptionStartsWith" in selector:
-            conditions.append(f"[starts-with(@content-desc, '{selector['descriptionStartsWith']}')]")
-
-        if "packageName" in selector:
-            conditions.append(f"[@package='{selector['packageName']}']")
-        elif "packageNameMatches" in selector:
-            conditions.append(f"[re:match(@package, '{selector['packageNameMatches']}')]")
-
-        if "resourceId" in selector:
-            conditions.append(f"[@resource-id='{selector['resourceId']}']")
-        elif "resourceIdMatches" in selector:
-            conditions.append(f"[re:match(@resource-id, '{selector['resourceIdMatches']}')]")
-
-        bool_props = [
-            "checkable", "checked", "clickable", "longClickable", "scrollable",
-            "enabled", "focusable", "focused", "selected", "covered"
-        ]
-        for prop in bool_props:
-            if prop in selector:
-                value = "true" if selector[prop] else "false"
-                conditions.append(f"[@{prop}='{value}']")
-
-        if "index" in selector:
-            conditions.append(f"[@index='{selector['index']}']")
-        elif "instance" in selector:
-            conditions.append(f"[@instance='{selector['instance']}']")
-
-        xpath += "".join(conditions)
-
-        if "childOrSibling" in selector and selector["childOrSibling"]:
-            for i, relation in enumerate(selector["childOrSibling"]):
-                sub_selector = selector["childOrSiblingSelector"][i]
-                sub_xpath = selector_to_xpath(sub_selector, False)  # 递归处理子选择器
-
-                if relation == "child":
-                    xpath += f"/{sub_xpath}"
-                elif relation == "sibling":
-                    xpath_initial = xpath
-                    xpath = '(' + xpath_initial + f"/following-sibling::{sub_xpath} | " + xpath_initial + f"/preceding-sibling::{sub_xpath})"
-
-        return xpath
-
-    except Exception as e:
-        print(f"Error occurred during selector conversion: {e}")
-        return "//error"
-
 def is_port_in_use(port: int) -> bool:
     with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
         return s.connect_ex(('127.0.0.1', port)) == 0
@@ -435,3 +424,25 @@ def get_free_port():
             if not is_port_in_use(port):
                 return port
         raise RuntimeError("No free port found")
+
+def set_covered_to_deepest_node(selector: u2.Selector):
+
+    def find_deepest_nodes(node):
+        deepest_node = None
+        is_leaf = True
+        if "childOrSibling" in node and node["childOrSibling"]:
+            for i, relation in enumerate(node["childOrSibling"]):
+                sub_selector = node["childOrSiblingSelector"][i]
+                deepest_node = find_deepest_nodes(sub_selector)
+                is_leaf = False
+
+        if is_leaf:
+            deepest_node = node
+        return deepest_node
+
+    deepest_node = find_deepest_nodes(selector)
+
+    if deepest_node is not None:
+        dict.update(deepest_node, {"covered": False})
+
+

kea2/utils.py

@@ -13,6 +13,7 @@ def getLogger(name: str) -> logging.Logger:
         if not logger.handlers:
             # Configure handler
             handler = logging.StreamHandler()
+            handler.flush = lambda: handler.stream.flush()  # 确保每次都flush
             formatter = logging.Formatter('[%(levelname)1s][%(asctime)s %(module)s:%(lineno)d pid:%(process)d] %(message)s')
             handler.setFormatter(formatter)
             logger.addHandler(handler)

{kea2_python-0.1.2.dist-info → kea2_python-0.2.0.dist-info}/METADATA

@@ -1,14 +1,15 @@
 Metadata-Version: 2.4
 Name: Kea2-python
-Version: 0.1.2
+Version: 0.2.0
 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
 Requires-Dist: jinja2>=3.0.0
+Requires-Dist: uiautomator2>=3.3.3
+Requires-Dist: adbutils>=2.9.3
 Dynamic: license-file
 
 
@@ -17,25 +18,41 @@ 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/1a64635b-a8f2-40f1-8f16-55e47b1d74e7" style="border-radius: 14px; width: 20%; height: 20%;"/> 
+    <img src="https://github.com/user-attachments/assets/aa5839fc-4542-46f6-918b-c9f891356c84" style="border-radius: 14px; width: 20%; height: 20%;"/> 
 </div>
 
-## About
+### Github repo link
+[https://github.com/ecnusse/Kea2](https://github.com/ecnusse/Kea2)
+
+### [点击此处：查看中文文档](README_cn.md)
+
+## About 
 
-Kea2 is an easy-to-use Python library for supporting, customizing and improving automated UI testing for mobile apps. Kea2's novelty is able to fuse the scripts (usually written by human) with automated UI testing tools, thus allowing many interesting and powerful features. 
+Kea2 is 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) and [uiautomator2](https://github.com/openatx/uiautomator2) and targets [Android](https://en.wikipedia.org/wiki/Android_(operating_system)) apps.
+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*.
+Kea2 currently targets [Android](https://en.wikipedia.org/wiki/Android_(operating_system)) apps.
+
+## Novelty & Important features
+
+<div align="center">
+    <div style="max-width:80%; max-height:80%">
+    <img src="docs/intro.png" style="border-radius: 14px; width: 80%; height: 80%;"/> 
+    </div>
+</div>
 
-## Important features
 - **Feature 1**(查找稳定性问题): coming with the full capability of [Fastbot](https://github.com/bytedance/Fastbot_Android) for stress testing and finding *stability problems* (i.e., *crashing bugs*); 
 
 - **Feature 2**(自定义测试场景\事件序列\黑白名单\黑白控件[^1]): customizing testing scenarios when running Fastbot (e.g., testing specific app functionalities, executing specific event traces, entering specifc UI pages, reaching specific app states, blacklisting specific activities/UI widgets/UI regions) with the full capability and flexibility powered by *python* language and [uiautomator2](https://github.com/openatx/uiautomator2);
 
-- **Feature 3**(支持断言机制[^2]): supporting auto-assertions when running Fastbot, based on the idea of [property-based testing](https://en.wikipedia.org/wiki/Software_testing#Property_testing) inheritted from [Kea](https://github.com/ecnusse/Kea), for finding *logic bugs* (i.e., *non-crashing bugs*)
+- **Feature 3**(支持断言机制[^2]): supporting auto-assertions when running Fastbot, based on the idea of [property-based testing](https://en.wikipedia.org/wiki/Software_testing#Property_testing) inheritted from [Kea](https://github.com/ecnusse/Kea), for finding *logic bugs* (i.e., *non-crashing functional bugs*).
 
+    For **Feature 2 and 3**, Kea2 allows you to focus on what app functionalities to be tested. You do not need to worry about how to reach these app functionalities. Just let Fastbot help. As a result, your scripts are usually short, robust and easy to maintain, and the corresponding app functionalities are much more stress-tested!
 
 **The ability of the three features in Kea2**
+
 |  | **Feature 1** | **Feature 2** | **Feature 3** |
 | --- | --- | --- | ---- |
 | **Finding crashes** | :+1: | :+1: | :+1: |
@@ -43,24 +60,17 @@ Kea2 is currently built on top of [Fastbot](https://github.com/bytedance/Fastbot
 | **Finding non-crashing functional (logic) bugs** |  |  | :+1: |
 
 
-<div align="center">
-    <div style="max-width:80%; max-height:80%">
-    <img src="docs/intro.png" style="border-radius: 14px; width: 80%; height: 80%;"/> 
-    </div>
-</div>
-
-
 
 ## Design & Roadmap
-Kea2, released as a Python library, currently works with:
-- [unittest](https://docs.python.org/3/library/unittest.html) as the testing framework;
+Kea2 currently works with:
+- [unittest](https://docs.python.org/3/library/unittest.html) as the testing framework to manage the scripts;
 - [uiautomator2](https://github.com/openatx/uiautomator2) as the UI test driver; 
 - [Fastbot](https://github.com/bytedance/Fastbot_Android) as the backend automated UI testing tool.
 
 In the future, Kea2 will be extended to support
-- [pytest](https://docs.pytest.org/en/stable/)
-- [Appium](https://github.com/appium/appium), [Hypium](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/hypium-python-guidelines) (for HarmonyOS/Open Harmony)
-- other automated UI testing tools (not limited to Fastbot)
+- [pytest](https://docs.pytest.org/en/stable/), another popular python testing framework;
+- [Appium](https://github.com/appium/appium), [Hypium](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/hypium-python-guidelines) (for HarmonyOS/Open Harmony);
+- any other automated UI testing tools (not limited to Fastbot)
 
 
 ## Installation
@@ -114,7 +124,7 @@ Test your app with the full capability of Fastbot for stress testing and finding
 kea2 run -s "emulator-5554" -p it.feio.android.omninotes.alpha --agent native --running-minutes 10 --throttle 200
 ```
 
-理解上述选项含义请查看[文档](docs/manual_en.md#launching-kea2)
+To understand the meanings of the options, you can see our [manual](docs/manual_en.md#launching-kea2).
 
 > The usage is similar to the the original Fastbot's [shell commands](https://github.com/bytedance/Fastbot_Android?tab=readme-ov-file#run-fastbot-with-shell-command). 
 
@@ -177,13 +187,14 @@ 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" >
-    <div >
-        <img src="docs/socialAppBug.png" style="border-radius: 14px; width:30%; height:40%;"/>
-    </div>
-    <p>The expected behavior (the upper figure) and the buggy behavior (the lower figure).
-<p/>
+<div align="center">
+    <img src="docs/socialAppBug.png" style="border-radius: 14px; width:30%; height:40%;"/>
+</div>
+
+<div align="center">
+    The expected behavior (the upper figure) and the buggy behavior (the lower figure).
 </div>
+    
 
 For the preceding always-holding property, we can write the following script to validate the functional correctness: when there is an `input_box` widget on the message sending page, we can type any non-empty string text into the input box and assert `send_button` should always exists.
 
@@ -208,12 +219,12 @@ You can run this example by using the similar command line in Feature 2.
 
 ## Documentations（更多文档）
 
-[更多文档](docs/manual_en.md)，包括了：
-- Kea2的案例教程（基于微信介绍）、
-- Kea2脚本的定义方法，支持的脚本装饰器(如`@precondition`、`@prob`、`@max_tries`)、
-- Kea2的启动方式、命令行选项
-- 查看/理解Kea2的运行结果（如界面截图、测试覆盖率、脚本执行成功与否）。
-- [如何黑白控件/区域](docs/blacklisting.md)
+You can find the [user manual](docs/manual_en.md), which includes:
+- Examples of using Kea2 on WeChat (in Chinese);
+- How to define Kea2's scripts and use the decorators (e.g., `@precondition`、`@prob`、`@max_tries`);
+- 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
 
 ## Open-source projects used by Kea2