Metadata-Version: 2.4
Name: devhelmkit
Version: 0.1.0
Summary: 跨平台 UI 自动化框架，当前聚焦 HarmonyOS
Author: devhelmkit contributors
License: Apache-2.0
Project-URL: Homepage, https://github.com/yabi-zzh/devhelmkit
Project-URL: Repository, https://github.com/yabi-zzh/devhelmkit
Project-URL: Documentation, https://github.com/yabi-zzh/devhelmkit/tree/main/docs
Project-URL: Issues, https://github.com/yabi-zzh/devhelmkit/issues
Keywords: harmonyos,uiautomator,ui-automation,testing,hypium
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: Pillow>=9.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: build>=1.0; extra == "dev"
Requires-Dist: twine>=4.0; extra == "dev"
Provides-Extra: webview
Requires-Dist: selenium>=4.0; extra == "webview"
Dynamic: license-file

﻿# devhelmkit

跨平台 UI 自动化框架，当前聚焦 HarmonyOS。

[![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
[![Python](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org)
[![Status](https://img.shields.io/badge/status-alpha-orange.svg)](#)

## 简介

devhelmkit 提供鸿蒙端 UI 自动化测试能力，通过 `hdc` 直连设备，无需依赖测试框架即可独立运行。

核心目标：

- **简洁 API**：`d(text="登录").click()`、`d.app_start()`、`d.dump_hierarchy()`
- **直连设备**：仅通过 `hdc` 通信，不依赖测试框架
- **跨平台抽象**：`BaseDriver` 契约层 + 平台具体实现，当前鸿蒙完整可用，Android 预留接口
- **保留高级能力**：鼠标、触控笔、指关节、触控板、多指手势等鸿蒙特性操作

## 特性

- 选择器链路：`d(text="xx")` / `d(id="xx")` / `d.xpath("//Text")`
- 控件操作：点击、长按、输入、拖拽、滑动、属性查询
- 设备控制：亮屏/息屏、解锁、按键、旋转、截图
- 应用管理：启动、停止、安装、卸载
- 高级手势：鼠标全套操作、触控笔（含压力）、指关节敲击、多指手势
- 触控板：多指滑动、滑动后停顿
- 事件监听：Toast 监听、UI 事件（对话框/窗口/组件事件）
- webview 自动化：通过 chromedriver + selenium 测试应用内 web 页面
- 双查找后端：uitest（设备端 RPC）+ uitree（本地 layout 解析）
- 资源管理：socket/端口转发自动清理，可选停止设备端守护进程
- 跨平台：支持 Windows / Linux / macOS，hdc 路径可配置

## 安装

### 前置条件

- **Python 3.8+**（支持 Windows / Linux / macOS）
- **HarmonyOS 设备**：已开启开发者模式与 USB 调试
- **hdc 命令行工具**：HarmonyOS Device Connector，用于与设备通信

#### 安装 hdc

hdc 随 HarmonyOS SDK 一起发布，获取方式：

1. 下载 [HarmonyOS SDK](https://developer.huawei.com/consumer/cn/download/)（选择 Command Line Tools for Windows/Linux/macOS）
2. 解压后，hdc 位于 `sdk/<version>/toolchains/` 目录下
3. 将该目录加入系统 `PATH` 环境变量
4. 验证安装：

```bash
hdc -v
# HarmonyOS Device Connector vX.X.X
```

连接设备后验证：

```bash
hdc list targets
# FMR0223824042727
```

### 安装 devhelmkit

#### 方式一：pip 安装（推荐）

```bash
pip install devhelmkit
```

#### 方式二：从源码安装

```bash
git clone https://github.com/devhelmkit/devhelmkit.git
cd devhelmkit
pip install -e .
```

### 依赖

- `Pillow>=9.0.0`（截图功能）

## 快速上手

```python
import devhelmkit

# 自动发现设备并连接
d = devhelmkit.connect()

# 启动应用
d.app_start("com.huawei.hmos.settings")

# 控件查找与操作
d(text="搜索").click()
d(className="TextInput").input_text("devhelmkit")

# 截图
d.screenshot().save("screen.png")

# 转储 UI 树
xml = d.dump_hierarchy()

# 关闭连接，释放 socket 与端口转发
d.close()
```

### 资源释放

推荐使用 `with` 语句或 `try/finally` 确保资源释放，无论是否异常都会
自动关闭 socket、清理 hdc 端口转发：

```python
import devhelmkit

with devhelmkit.connect() as d:
    d.app_start("com.huawei.hmos.settings")
    d(text="搜索").click()
# 退出 with 块时自动调用 close()
```

如需在关闭时同时停止设备端 uitest 守护进程（默认保留以便复用）：

```python
# 方式一：运行时指定
d.close(stop_daemon=True)

# 方式二：通过配置项
from devhelmkit.harmony.config import HarmonyDriverConfig

config = HarmonyDriverConfig(stop_daemon_on_close=True)
d = devhelmkit.connect(config=config)
```

### 运行示例

仓库内置完整 demo，演示连接 → 操作 → 释放全流程：

```bash
# 基础示例（保留设备端守护进程）
python examples/quickstart.py

# 完整示例（退出时停止设备端守护进程）
python examples/quickstart.py --stop-daemon

# 指定设备序列号
python examples/quickstart.py FMR0223824042727
```

### 指定设备

```python
# 多设备时指定序列号
d = devhelmkit.connect(serial="1234567890ABCDEF")

# 显式指定平台
d = devhelmkit.connect(platform="harmony")
```

### 指定 hdc 路径

当 hdc 未加入系统 PATH，或需指定特定版本时：

```python
import devhelmkit
from devhelmkit.harmony.device.hdc import HdcDevice

# 全局设置 hdc 路径（影响后续所有连接）
HdcDevice.set_hdc_path("/path/to/hdc")

d = devhelmkit.connect()
```

或通过配置项：

```python
from devhelmkit.harmony.config import HarmonyDriverConfig

config = HarmonyDriverConfig(hdc_path="/path/to/hdc")
d = devhelmkit.connect(config=config)
```

## API 示例

### 控件操作

```python
# 等待控件出现
d(text="登录").wait(timeout=10)

# 输入文本
d(id="username").input_text("admin")

# 清空文本
d(id="username").clear_text()

# 长按
d(text="项目").long_click()

# 拖拽
d(text="A").drag_to(text="B")

# 获取属性
print(d(text="标题").info)
```

### 手势

```python
# 滑动
d.swipe(100, 500, 100, 100)

# 多指手势
d.two_finger_swipe((0, 400), (200, 400), (880, 400), (680, 400))

# 自定义手势
from devhelmkit.model.input import GestureAction

g = GestureAction()
g.add_step("move", 100, 200)
g.add_step("move", 200, 300)
d.inject_gesture(g, speed=1000)
```

### 鼠标操作

```python
# 鼠标点击（左键）
d.mouse_click((500, 500))

# 鼠标右键
d.mouse_click((500, 500), button_id=1)

# 鼠标滚轮
d.mouse_scroll((500, 500), "down", steps=3)

# 鼠标拖拽
d.mouse_drag((100, 100), (300, 300))
```

### 触控笔

```python
# 触控笔点击
d.pen_click((500, 500))

# 触控笔长按（带压力）
d.pen_long_click((500, 500), pressure=0.8)

# 触控笔方向滑动
d.pen_swipe("UP", distance=60)
```

### 事件监听

```python
# Toast 监听
d.start_listen_toast()
d(text="提交").click()
print("Toast:", d.get_latest_toast(timeout=3))

# 检查 Toast
if d.check_toast("保存成功", fuzzy="contains"):
    print("操作成功")
```

### 设备控制

```python
# 亮屏/息屏
d.wake_up_display()
d.close_display()

# 按键
d.press_keycode(23)  # 确认键

# 截图
img = d.screenshot()
img.save("capture.png")

# 安装应用
d.app_install("/path/to/app.hap")
```

### webview 自动化

webview 测试需要安装可选依赖 `selenium` 与 chromedriver：

```bash
# 安装 webview 可选依赖
pip install devhelmkit[webview]
```

chromedriver 需按设备 webview 版本下载，放置于目录：

```text
chromedriver_search_path/
├── chromedriver_114/
│   ├── chromedriver.exe      # Windows
│   ├── chromedriver          # Linux
│   └── chromedriver.mac      # macOS
└── chromedriver_132/
    ├── chromedriver.exe
    ├── chromedriver
    └── chromedriver.mac
```

使用方式：

```python
# 连接应用 webview
wv = d.webview(
    "com.huawei.hmos.browser",
    chromedriver_search_path="/path/to/chromedriver_search_path"
)

# 通过 selenium webdriver 操作页面
wv.driver.get("https://www.baidu.com")
wv.driver.find_element("id", "kw").send_keys("devhelmkit")

# 释放资源（移除端口转发 + quit webdriver + 停止 chromedriver）
wv.close()
```

## 架构

```text
devhelmkit/
├── core/          # 跨平台契约层（BaseDriver / BaseComponent / SelectorSpec）
├── model/         # 纯数据类型（Rect / KeyCode / GestureAction / ...）
├── harmony/       # HarmonyOS 平台实现
│   ├── driver.py      # 平台驱动门面
│   ├── device/        # hdc 命令封装与 RPC 通道
│   ├── rpc/           # bin 模式 RPC 协议与远程对象管理
│   ├── finder/        # 控件查找（uitest + uitree 双后端）
│   ├── agent/         # 设备端 uitest 守护进程管理
│   └── webview/       # webview 自动化（chromedriver + selenium）
├── android/       # Android 平台预留（阶段四）
├── utils/         # 通用工具（日志/重试/超时）
├── assets/so/     # 设备端 agent.so 资产
├── examples/      # 示例代码（quickstart.py）
└── tests/         # 单元测试与集成测试
```

详细设计文档见 [docs/design/](docs/design/README.md)。

## 开发

### 运行测试

```bash
# 离线单元测试（无需设备）
python tests/test_api_offline.py

# 真机集成测试
python tests/test_device_info.py <设备SN>
```

### 代码结构约定

- `core/` 禁止依赖平台实现层
- `model/` 无内部依赖，可跨平台复用
- 平台实现层内部按 `device/`、`rpc/`、`finder/` 分包
- RPC 层不认识 UI 对象，设备通道不理解控件定位

## 贡献

欢迎提交 Issue 与 Pull Request。提交前请确保：

1. 代码通过离线测试：`python tests/test_api_offline.py`
2. 遵循现有代码风格与分层约束
3. 新增 API 需同步更新 [API 接口文档](docs/api_reference.md)

## 许可证

[Apache License 2.0](LICENSE)
