devhelmkit 0.1.0__py3-none-any.whl

devhelmkit/harmony/webview/webview_driver.py

@@ -0,0 +1,326 @@
+# !/usr/bin/env python
+# -*- coding: utf-8 -*-
+"""WebViewDriver：webview 自动化驱动。
+
+连接设备端 webview，通过 selenium webdriver 提供页面级自动化能力。
+
+完整流程：
+  1. 探测 devtools 端口（domain socket 或 tcp）
+  2. 建立 hdc 端口转发（本地端口 -> 设备端 devtools）
+  3. 查询 webview 内核版本
+  4. 启动匹配版本的 chromedriver
+  5. 通过 selenium Remote 连接
+  6. 资源释放：移除端口转发 + quit webdriver + 停止 chromedriver
+
+使用方式：
+    from devhelmkit.harmony.webview import WebViewDriver
+
+    wv = WebViewDriver(device)
+    wv.connect("com.huawei.hmos.browser")
+    wv.driver.get("https://www.baidu.com")
+    wv.close()
+
+或通过 HarmonyDriver 入口：
+    d.webview("com.huawei.hmos.browser")
+"""
+import json
+import re
+import time
+import urllib.request
+from typing import Optional, TYPE_CHECKING
+
+from devhelmkit.exceptions import DevhelmError
+from devhelmkit.harmony.webview.chromedriver_manager import ChromedriverManager
+from devhelmkit.harmony.webview.devtools_finder import DevtoolsFinder
+from devhelmkit.utils import logger
+
+if TYPE_CHECKING:
+    from selenium.webdriver.remote.webdriver import WebDriver
+    from devhelmkit.harmony.device.hdc import HdcDevice
+
+# 默认本地 devtools 端口（自动分配空闲端口）
+DEFAULT_DEVTOOL_PORT = 9222
+
+# 默认连接超时（秒）
+DEFAULT_CONNECTION_TIMEOUT = 60
+
+# 页面加载超时（秒）
+DEFAULT_PAGE_LOAD_TIMEOUT = 50
+
+# 脚本执行超时（秒）
+DEFAULT_SCRIPT_TIMEOUT = 50
+
+# 隐式等待（秒）
+IMPLICIT_WAIT_TIMEOUT = 20
+
+
+class WebViewDriver:
+    """webview 自动化驱动，封装 selenium webdriver 连接与资源管理。"""
+
+    def __init__(self, device: "HdcDevice",
+                 chromedriver_search_path: str = "",
+                 chromedriver_exe_path: str = "",
+                 chromedriver_port: int = 9515):
+        """
+        Args:
+            device: HdcDevice 实例
+            chromedriver_search_path: chromedriver 存放目录（多版本结构）
+            chromedriver_exe_path: 直接指定 chromedriver 路径（优先）
+            chromedriver_port: chromedriver 监听端口
+        """
+        self._device = device
+        self._bundle_name: Optional[str] = None
+        self._driver: Optional["WebDriver"] = None
+        self._devtool_port = DEFAULT_DEVTOOL_PORT
+        self._remote_devtool_port = DEFAULT_DEVTOOL_PORT
+        self._fport_established = False
+
+        self._finder = DevtoolsFinder(device)
+        self._chromedriver = ChromedriverManager(
+            search_path=chromedriver_search_path,
+            exe_path=chromedriver_exe_path,
+            port=chromedriver_port,
+        )
+
+    @property
+    def driver(self) -> "WebDriver":
+        """selenium webdriver 实例。
+
+        未连接时抛异常，确保调用前已 connect。
+        """
+        if self._driver is None:
+            raise DevhelmError("webview 未连接，请先调用 connect()")
+        return self._driver
+
+    @property
+    def devtools_url(self) -> str:
+        """本地 devtools 访问地址。"""
+        return "http://127.0.0.1:%d" % self._devtool_port
+
+    def connect(self, bundle_name: str,
+                remote_devtools_port: Optional[int] = None,
+                connection_timeout: int = DEFAULT_CONNECTION_TIMEOUT,
+                options=None) -> "WebDriver":
+        """连接指定应用的 webview。
+
+        Args:
+            bundle_name: 目标应用包名
+            remote_devtools_port: 自定义 webview 内核的 devtools 端口；
+                                  系统 web 内核无需指定，自动探测
+            connection_timeout: 连接超时（秒）
+            options: 传递给 selenium webdriver 的 options
+
+        Returns:
+            selenium WebDriver 实例
+
+        Raises:
+            DevhelmError: 连接失败
+        """
+        self._bundle_name = bundle_name
+        self.close()
+        self._setup_port_forward(bundle_name, remote_devtools_port)
+        webview_version = self._get_webview_version()
+        self._chromedriver.start(webview_version)
+        self._driver = self._connect_selenium(options, connection_timeout)
+        return self._driver
+
+    def close(self) -> None:
+        """释放资源：移除端口转发 + quit webdriver + 停止 chromedriver。"""
+        if self._driver is not None:
+            try:
+                self._driver.quit()
+            except Exception as e:
+                logger.warn("quit webdriver 异常: %s", e)
+            finally:
+                self._driver = None
+
+        self._remove_port_forward()
+
+        if self._chromedriver is not None:
+            self._chromedriver.stop()
+
+    def switch_to_visible_window(self, index: int = 0) -> None:
+        """切换到 visible 状态的窗口。
+
+        Args:
+            index: 第几个可见窗口（0 表示第一个）
+        """
+        driver = self.driver
+        handles = driver.window_handles
+        if index < 0:
+            handles = list(reversed(handles))
+            index = abs(index) - 1
+        if index >= len(handles):
+            raise ValueError("窗口索引越界: %d (共 %d 个)" % (index, len(handles)))
+
+        count = index
+        for handle in handles:
+            driver.switch_to.window(handle)
+            visible = driver.execute_script("return document.visibilityState")
+            if visible == "visible":
+                if count == 0:
+                    return
+                count -= 1
+
+    def get_all_windows(self, with_url: bool = False) -> list:
+        """获取所有窗口信息。
+
+        Args:
+            with_url: True 返回包含 url/title/visible 的字典列表
+        """
+        if not with_url:
+            return self.driver.window_handles
+
+        driver = self.driver
+        current = driver.current_window_handle
+        result = []
+        for handle in driver.window_handles:
+            driver.switch_to.window(handle)
+            result.append({
+                "handle": handle,
+                "url": driver.current_url,
+                "title": driver.title,
+                "visible": driver.execute_script("return document.visibilityState"),
+            })
+        driver.switch_to.window(current)
+        return result
+
+    def __getattr__(self, name):
+        """代理未找到的属性到 selenium webdriver。"""
+        return getattr(self._driver, name)
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        self.close()
+
+    # ============================================================
+    # 内部实现
+    # ============================================================
+
+    def _setup_port_forward(self, bundle_name: str,
+                            remote_devtools_port: Optional[int]) -> None:
+        """建立 hdc 端口转发。"""
+        self._devtool_port = _get_unused_port()
+
+        if remote_devtools_port is not None:
+            # 自定义 webview 内核，指定 tcp 端口
+            self._remote_devtool_port = remote_devtools_port
+            if not self._finder.check_tcp_port(remote_devtools_port):
+                raise DevhelmError(
+                    "设备端 devtools 端口 %d 未开放，请检查应用是否已开启 web 调试"
+                    % remote_devtools_port
+                )
+            self._device.shell(
+                "hdc fport tcp:%d tcp:%d" % (self._devtool_port, remote_devtools_port)
+            )
+        elif self._finder.is_using_domain_socket():
+            # 系统 web 内核，通过 domain socket 探测
+            socket_name = self._finder.find_devtools_socket(bundle_name)
+            if socket_name is None:
+                raise DevhelmError(
+                    "未找到 %s 的 devtools socket，请检查应用是否已开启 web 调试"
+                    % bundle_name
+                )
+            self._device.shell(
+                "hdc fport tcp:%d localabstract:%s"
+                % (self._devtool_port, socket_name)
+            )
+        else:
+            # 未指定端口且非 domain socket，尝试默认 tcp 端口
+            if not self._finder.check_tcp_port(self._remote_devtool_port):
+                raise DevhelmError(
+                    "设备端 devtools 端口 %d 未开放" % self._remote_devtool_port
+                )
+            self._device.shell(
+                "hdc fport tcp:%d tcp:%d"
+                % (self._devtool_port, self._remote_devtool_port)
+            )
+
+        self._fport_established = True
+        logger.info(
+            "devtools 端口转发已建立: tcp:%d -> 设备 (bundle=%s)",
+            self._devtool_port, bundle_name
+        )
+
+    def _remove_port_forward(self) -> None:
+        """移除 hdc 端口转发。"""
+        if not self._fport_established:
+            return
+        try:
+            self._device.shell("hdc fport rm tcp:%d" % self._devtool_port)
+        except Exception as e:
+            logger.warn("移除端口转发异常: %s", e)
+        finally:
+            self._fport_established = False
+
+    def _get_webview_version(self, retry: int = 3) -> int:
+        """查询设备端 webview 内核版本。
+
+        通过 devtools /json/version 接口获取。
+        """
+        for _ in range(retry):
+            try:
+                resp = urllib.request.urlopen(
+                    self.devtools_url + "/json/version", timeout=5
+                ).read().decode("utf-8", errors="ignore")
+                info = json.loads(resp)
+                browser = info.get("Browser", "")
+                match = re.search(r"/(\d+)\.", browser)
+                if match:
+                    version = int(match.group(1))
+                    logger.info("webview 内核版本: %d", version)
+                    return version
+                logger.warn("未知 webview 版本信息: %s", resp)
+            except Exception as e:
+                logger.warn("查询 webview 版本失败: %s", e)
+        logger.warn("无法获取 webview 版本，回退到 114")
+        return 114
+
+    def _connect_selenium(self, options, timeout: int) -> "WebDriver":
+        """通过 selenium Remote 连接 chromedriver。"""
+        try:
+            from selenium import webdriver
+            from selenium.webdriver.remote.remote_connection import RemoteConnection
+        except ImportError as e:
+            raise DevhelmError(
+                "selenium 未安装，请执行 pip install selenium 或 pip install devhelmkit[webview]"
+            ) from e
+
+        RemoteConnection.set_timeout(timeout)
+
+        if options is None:
+            options = webdriver.ChromeOptions()
+        options.add_experimental_option(
+            "debuggerAddress", "127.0.0.1:%d" % self._devtool_port
+        )
+
+        try:
+            driver = webdriver.Remote(
+                command_executor=self._chromedriver.host,
+                options=options
+            )
+        except Exception as e:
+            logger.error("连接 chromedriver 失败: %s", e)
+            self._chromedriver.stop()
+            raise DevhelmError("selenium webdriver 连接失败: %s" % e) from e
+
+        driver.set_page_load_timeout(DEFAULT_PAGE_LOAD_TIMEOUT)
+        driver.set_script_timeout(DEFAULT_SCRIPT_TIMEOUT)
+        driver.implicitly_wait(IMPLICIT_WAIT_TIMEOUT)
+
+        logger.info("webview 已连接, 窗口数: %d", len(driver.window_handles))
+        logger.info("当前页面: %s", driver.current_url)
+        return driver
+
+
+def _get_unused_port() -> int:
+    """获取一个本地空闲端口。"""
+    import socket
+    sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+    try:
+        sock.bind(("127.0.0.1", 0))
+        return sock.getsockname()[1]
+    finally:
+        sock.close()

devhelmkit/model/__init__.py

@@ -0,0 +1,3 @@
+# !/usr/bin/env python
+# -*- coding: utf-8 -*-
+"""纯数据类型层：不依赖 core / harmony / android / utils。"""

devhelmkit/model/action.py

@@ -0,0 +1,147 @@
+# !/usr/bin/env python
+# -*- coding: utf-8 -*-
+"""操作类型与上下文：ActionType / ActionTrackGroup / ActionContext / ActionContextStack。
+
+ActionContextStack 持有 driver 的 weakref.proxy，避免循环引用。
+"""
+import weakref
+from typing import List, Optional, Tuple
+
+from devhelmkit.exceptions import DevhelmError
+
+
+class ActionType:
+    """操作类型常量。"""
+    CLICK = "click"
+    DOUBLE_CLICK = "double_click"
+    LONG_CLICK = "long_click"
+    SWIPE = "swipe"
+    DRAG = "drag"
+    PINCH_IN = "pinch_in"
+    PINCH_OUT = "pinch_out"
+    INPUT_TEXT = "input_text"
+    PRESS_KEY = "press_key"
+    MOUSE_SCROLL = "mouse_scroll"
+
+
+class ActionTrackGroup:
+    """操作路径信息。
+
+    使用 __init__ 接收可变参数 *points_group，每个参数是 list[(x, y)]。
+    """
+
+    def __init__(self, *points_group):
+        if len(points_group) <= 0:
+            raise DevhelmError("No data for ActionTrackGroup")
+        for points in points_group:
+            if not isinstance(points, list):
+                raise TypeError("Invalid point_list: %s" % points)
+            for point in points:
+                x, y = point  # 解包校验
+        self._trace_group: List[List[Tuple[int, int]]] = list(points_group)
+
+    def __getitem__(self, item):
+        return self._trace_group[item]
+
+    @property
+    def first_track(self):
+        if len(self._trace_group) < 1:
+            raise DevhelmError("No data in this ActionTraceGroup")
+        return self[0]
+
+
+class ActionContext:
+    """单次操作上下文。"""
+
+    def __init__(self, level: int = 0):
+        self.level = level
+        self.reset()
+
+    def reset(self):
+        self.action_desc: Optional[str] = None
+        self.action_type: Optional[str] = None
+        self.pre_page = None
+        self.next_page = None
+        self.target_selector = None
+        self.target_component = None
+        self.target_recognize_page = None
+        self.action_runnable = None
+        self.allow_skip = False
+        self.metrics = None
+
+    def __repr__(self):
+        return str(self.action_desc)
+
+
+class ActionContextStack:
+    """操作上下文栈。
+
+    用于嵌套操作时管理上下文层级，向栈底传递页面/控件信息。
+    持有 driver 的 weakref.proxy 避免循环引用，支持 with 语法，
+    仅最顶层 action 通知 HookExtensionManager。
+    """
+
+    def __init__(self, driver):
+        self.stack: List[ActionContext] = []
+        self.default_context = ActionContext()
+        self.driver = weakref.proxy(driver)
+        self.last_action: Optional[ActionContext] = None
+
+    def push(self) -> ActionContext:
+        new_context = ActionContext(len(self.stack))
+        self.stack.append(new_context)
+        return new_context
+
+    def pop(self, success: bool = True) -> Optional[ActionContext]:
+        if len(self.stack) <= 0:
+            return None
+        current_action_ctx = self.stack.pop()
+        self._set_upper_level_info()
+        if len(self.stack) <= 0 and success and (not current_action_ctx.allow_skip):
+            self.last_action = current_action_ctx
+        return current_action_ctx
+
+    def _set_upper_level_info(self):
+        """向栈底传递页面/控件信息。"""
+        if len(self.stack) < 1:
+            return
+        top_item = self.top_item
+        for item in reversed(self.stack[:-1]):
+            if item.pre_page is None:
+                item.pre_page = top_item.pre_page
+            if item.next_page is None:
+                item.next_page = top_item.next_page
+            item.target_recognize_page = top_item.target_recognize_page
+            item.target_component = top_item.target_component
+            item.target_selector = top_item.target_selector
+
+    def __len__(self):
+        return len(self.stack)
+
+    @property
+    def top_item(self) -> ActionContext:
+        if len(self.stack) == 0:
+            return self.default_context
+        return self.stack[-1]
+
+    @property
+    def bottom_item(self) -> ActionContext:
+        if len(self.stack) == 0:
+            return self.default_context
+        return self.stack[0]
+
+    def enter_new_context(self, action_type: str, action_desc: str,
+                          action_runnable=None, metrics=None):
+        ctx = self.push()
+        ctx.action_type = action_type
+        ctx.action_desc = action_desc
+        ctx.action_runnable = action_runnable
+        ctx.metrics = metrics
+        return self
+
+    def __enter__(self) -> ActionContext:
+        return self.top_item
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        self.pop(exc_val is None)
+        return False

devhelmkit/model/app_state.py

@@ -0,0 +1,50 @@
+# !/usr/bin/env python
+# -*- coding: utf-8 -*-
+"""应用与窗口状态类型：AppState / WindowMode / ResizeDirection /
+WindowState / OSType。"""
+from dataclasses import dataclass
+from enum import IntEnum
+from typing import Optional, Tuple
+
+
+class AppState(IntEnum):
+    """应用状态。"""
+    FOREGROUND = 0
+    BACKGROUND = 1
+
+
+class WindowMode(IntEnum):
+    """窗口模式。"""
+    FULLSCREEN = 0
+    PRIMARY = 1
+    SECONDARY = 2
+    FLOATING = 3
+
+
+class ResizeDirection(IntEnum):
+    """窗口调整大小方向。"""
+    LEFT = 0
+    RIGHT = 1
+    TOP = 2
+    BOTTOM = 3
+    TOP_LEFT = 4
+    TOP_RIGHT = 5
+    BOTTOM_LEFT = 6
+    BOTTOM_RIGHT = 7
+
+
+@dataclass
+class WindowState:
+    """窗口状态。"""
+    window_id: str
+    mode: WindowMode
+    bounds: Optional[Tuple[int, int, int, int]] = None
+
+    def is_fullscreen(self) -> bool:
+        return self.mode == WindowMode.FULLSCREEN
+
+
+class OSType:
+    """操作系统类型（类常量风格）。"""
+    OHOS = "OHOS"
+    HMOS = "HMOS"

devhelmkit/model/constants.py

@@ -0,0 +1,22 @@
+# !/usr/bin/env python
+# -*- coding: utf-8 -*-
+"""常量定义。"""
+
+# 超时与等待
+INPUT_TEXT_WAIT_TIME = 1
+DEFAULT_IDLE_TIME = 0.5
+DEFAULT_SLIDE_TIME = 0.3
+MAX_TIMEOUT = 60
+DEFAULT_TIMEOUT = 5
+WAIT_FOR_INSTALL_TIME = 3
+FAST_SWIPE_TIME = 0.25
+SWIPE_INTERVAL = 0.5
+
+# 手势参数
+NAV_GESTURE_SPEED = 8000
+DEFAULT_SWIPE_DURATION = 0.5
+DEFAULT_DOUBLE_CLICK_INTERVAL = 0.15
+DEFAULT_LONG_CLICK_INTERVAL = 1
+
+# 内部常量
+FULL_DRIVER_TMP_KEY = "_tmp_full_uidriver"

devhelmkit/model/display.py

@@ -0,0 +1,32 @@
+# !/usr/bin/env python
+# -*- coding: utf-8 -*-
+"""显示器相关类型：DisplayRotation / DisplayInfo。"""
+from dataclasses import dataclass
+from enum import IntEnum
+from typing import Tuple
+
+
+class DisplayRotation(IntEnum):
+    """屏幕旋转状态。"""
+    PORTRAIT = 0
+    LANDSCAPE = 1
+    REVERSE_PORTRAIT = 2
+    REVERSE_LANDSCAPE = 3
+
+
+@dataclass
+class DisplayInfo:
+    """显示器信息。"""
+    display_id: int
+    width: int
+    height: int
+    density: int
+    rotation: DisplayRotation = DisplayRotation.PORTRAIT
+
+    @property
+    def size(self) -> Tuple[int, int]:
+        return (self.width, self.height)
+
+    def is_portrait(self) -> bool:
+        return self.rotation in (DisplayRotation.PORTRAIT,
+                                 DisplayRotation.REVERSE_PORTRAIT)

devhelmkit/model/format_string.py

@@ -0,0 +1,24 @@
+# !/usr/bin/env python
+# -*- coding: utf-8 -*-
+"""FormatString：带变量的模板字符串。
+
+通过 __getattr__ 转发 template 字符串的方法，使其可像 str 一样使用。
+"""
+
+
+class FormatString:
+    """格式化字符串（带变量的模板字符串）。"""
+
+    def __init__(self, template: str, **kwargs):
+        self.template = template
+        self.variables = kwargs
+
+    def __getattr__(self, item):
+        # 转发 template 字符串的方法
+        return getattr(self.template, item)
+
+    def __str__(self):
+        return self.template
+
+    def __repr__(self):
+        return self.template

devhelmkit/model/input.py

@@ -0,0 +1,50 @@
+# !/usr/bin/env python
+# -*- coding: utf-8 -*-
+"""输入设备与手势类型：InputDevice / MouseButton / GestureStep /
+TouchPadSwipeOptions / GestureAction。"""
+from dataclasses import dataclass, field
+from enum import IntEnum
+from typing import List, Optional
+
+
+class InputDevice(IntEnum):
+    """输入设备类型。"""
+    TOUCH = 0
+    MOUSE = 1
+    PEN = 2
+    KNUCKLE = 3
+    TOUCHPAD = 4
+
+
+class MouseButton(IntEnum):
+    """鼠标按键。"""
+    LEFT = 0
+    RIGHT = 1
+    MIDDLE = 2
+
+
+@dataclass
+class GestureStep:
+    """手势步骤。"""
+    action: str
+    x: int
+    y: int
+    duration: float = 0.0
+
+
+@dataclass
+class TouchPadSwipeOptions:
+    """触控板滑动选项。"""
+    speed: Optional[int] = None
+    step_length: Optional[int] = None
+
+
+@dataclass
+class GestureAction:
+    """手势动作。"""
+    steps: List[GestureStep] = field(default_factory=list)
+    input_device: InputDevice = InputDevice.TOUCH
+
+    def add_step(self, action: str, x: int, y: int, duration: float = 0.0):
+        """添加手势步骤。"""
+        self.steps.append(GestureStep(action=action, x=x, y=y, duration=duration))

devhelmkit/model/json_base.py

@@ -0,0 +1,42 @@
+# !/usr/bin/env python
+# -*- coding: utf-8 -*-
+"""JsonBase：JSON 序列化基类。
+
+过滤 None 值、支持 api_level 参数、不使用 @dataclass，确保 RPC 协议兼容性。
+"""
+import json
+from typing import Any, Dict
+
+
+class JsonBase:
+    """JSON 序列化基类。"""
+
+    def to_dict(self, api_level: int = 9) -> Dict[str, Any]:
+        """转换为字典（过滤 None 值）。
+
+        Args:
+            api_level: API 版本级别，用于版本兼容。
+        """
+        result = {}
+        for key, value in self.__dict__.items():
+            if value is not None:
+                result[key] = value
+        return result
+
+    def to_json(self) -> str:
+        """转换为 JSON 字符串。"""
+        return json.dumps(self.to_dict(), ensure_ascii=False,
+                          separators=(',', ':'))
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]):
+        """从字典创建实例。"""
+        obj = cls.__new__(cls)
+        for key, value in data.items():
+            setattr(obj, key, value)
+        return obj
+
+    @classmethod
+    def from_json(cls, json_str: str):
+        """从 JSON 字符串创建实例。"""
+        return cls.from_dict(json.loads(json_str))