https://github.com/ziguiway/hmnextauto
UI Automation Framework for HarmonyOS NEXT - uiautomator2-compatible API, zero learning cost
https://github.com/ziguiway/hmnextauto
automation-testing harmony harmonyos harmonyos-next harmonyosnext hdc mobile-testing python ui-automation uiautomator2
Last synced: 5 days ago
JSON representation
UI Automation Framework for HarmonyOS NEXT - uiautomator2-compatible API, zero learning cost
- Host: GitHub
- URL: https://github.com/ziguiway/hmnextauto
- Owner: ziguiway
- License: mit
- Created: 2026-04-30T07:56:02.000Z (about 2 months ago)
- Default Branch: main
- Last Pushed: 2026-05-03T03:44:05.000Z (about 2 months ago)
- Last Synced: 2026-05-03T05:15:38.770Z (about 2 months ago)
- Topics: automation-testing, harmony, harmonyos, harmonyos-next, harmonyosnext, hdc, mobile-testing, python, ui-automation, uiautomator2
- Language: Python
- Homepage: https://pypi.org/project/hmnextauto/
- Size: 5.56 MB
- Stars: 1
- Watchers: 0
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-python-testing - HMNextAuto - Python-based UI automation framework for HarmonyOS NEXT. API compatible with uiautomator2, supports XPath, image recognition, performance monitoring and notification management. (UI Testing)
README
# HMNextAuto 鸿蒙自动化框架
[](https://pypi.python.org/pypi/hmnextauto)
[](https://pypi.org/project/hmnextauto)
[](https://github.com/ziguiway/HMNextAuto/blob/main/LICENSE)
[](https://pepy.tech/project/hmnextauto)
> **持续维护的鸿蒙 NEXT 无侵入式 UI 自动化框架**，对齐 uiautomator2 API，零学习成本！
***
## 🌍 项目背景
随着华为鸿蒙 NEXT 系统的正式发布，纯血鸿蒙生态正在快速崛起。与传统 HarmonyOS 不同，HarmonyOS NEXT 不再兼容 Android 应用，这意味着基于 Android 的自动化测试框架（如 uiautomator2）将无法在新系统上运行。
在这样的背景下，原 [hmdriver2](https://github.com/codematrixer/hmdriver2) 项目应运而生，它是首款支持 HarmonyOS NEXT 的无侵入式 UI 自动化框架，为开发者提供了轻量高效的自动化测试能力。然而，由于原作者工作变动等原因，该项目已经两年没有更新维护。
为了让这款优秀的框架继续服务于广大鸿蒙开发者，我基于原 `hmdriver2` 的核心架构，完成了大量的 Bug 修复、功能增强和稳定性优化。**HMNextAuto** 由此诞生！
***
## 🌟 核心优势
| 特性 | HMNextAuto | Hypium (官方) | 原版 hmdriver2 |
| ----------- | :--------------------: | :---------: | :----------: |
| 无侵入式 | ✅ | ❌ 需安装测试框架 | ✅ |
| 学习成本 | 🟢 零学习成本（对齐 u2） | 🔴 较高 | 🟡 需熟悉 API |
| 维护状态 | ✅ 持续更新 | ✅ 官方维护 | ❌ 停止维护 2 年 |
| 视觉定位 | ✅ 多尺度模板匹配 | ❌ | ❌ |
| 找色点击 | ✅ RGB 容差匹配 | ❌ | ❌ |
| 后台 Watcher | ✅ 纯 Python 实现 | ❌ | ✅ |
| XPath 多元素操作 | ✅ count/all/first/last | ❌ | ❌ |
| 通知栏操作 | ✅ 完整通知栏控制 | ❌ | ❌ |
| 性能监控 | ✅ 后台性能采集 | ❌ | ❌ |
| 智能等待条件 | ✅ wait\_until | ❌ | ❌ |
| 依赖复杂度 | 🟢 仅 lxml + opencv | 🔴 重 | 🟢 轻 |
***
## 📋 系统要求
| 项目 | 要求 |
| ------ | ---------------------------------- |
| Python | 3.8+ |
| 操作系统 | Windows / macOS / Linux |
| 设备 | HarmonyOS NEXT (API 12+) |
| 工具 | HDC (HarmonyOS Command Line Tools) |
***
## 🚀 快速开始
### 1. 安装 HDC 工具
下载 [HarmonyOS Command Line Tools](https://developer.huawei.com/consumer/cn/download/) 并配置环境变量：
```bash
# macOS / Linux
export HM_SDK_HOME="/path/to/sdk"
export PATH=$PATH:$HM_SDK_HOME/openharmony/toolchains
# Windows (系统环境变量)
HM_SDK_HOME=C:\path\to\sdk
PATH=%PATH%;%HM_SDK_HOME%\openharmony\toolchains
```
### 2. 连接设备
开启 USB 调试，确认设备连接：
```bash
hdc list targets
# 输出设备序列号即连接成功
```
### 3. 安装 HMNextAuto
```bash
pip install -U hmnextauto
```
### 4. 验证安装
```python
from hmnextauto.driver import Driver
d = Driver()
print(d.device_info)
# 输出设备信息即配置成功
```
***
## ✨ 增强功能详解
> 以下功能均为 HMNextAuto 相比原版 hmdriver2 的**新增增强功能**
### 1. XPath 多元素操作 🆕
支持对匹配到的多个元素进行批量操作：
```python
# 获取匹配元素数量
count = d.xpath('//*[@clickable="true"]').count
# 获取所有匹配元素
elements = d.xpath('//*[@clickable="true"]').all()
for el in elements:
print(el.bounds)
el.click()
# 快速获取首/末元素
first = d.xpath('//*[@clickable="true"]').first()
last = d.xpath('//*[@clickable="true"]').last()
```
### 2. 通知栏操作 🆕
完整的下拉通知栏和快捷开关控制：
```python
# 打开通知栏（消息中心）
d.notification.open()
# 打开快捷设置面板
d.notification.open_quick_settings()
# 点击快捷开关
d.notification.click_quick_setting("wifi") # WiFi
d.notification.click_quick_setting("bluetooth") # 蓝牙
d.notification.click_quick_setting("airplane") # 飞行模式
d.notification.click_quick_setting("flashlight") # 手电筒
# 设置亮度 (0-255)
d.notification.set_brightness(128)
# 关闭通知栏
d.notification.close()
```
### 3. 性能监控与分析 🆕
后台自动采集设备性能数据，支持深度分析和报告生成：
```python
# 基础用法 - 后台采集
with d.performance_watcher.start("perf.jsonl", interval=0.5):
d(text="按钮").click()
# ... 执行测试 ...
# 高级用法 - 选择性采集（推荐，更快）
d.performance_watcher.configure(
metrics=["fps", "cpu", "memory", "hitches"],
package="com.example.app", # 指定包名加速内存采集
interval=0.5
).start("perf.jsonl")
# 深度分析
analyzer = d.performance_watcher.analyze()
# 统计摘要
stats = analyzer.stats()
print(f"FPS 平均: {stats.fps.avg}, P95: {stats.fps.p95}")
print(f"内存峰值: {stats.memory_peak_mb:.1f} MB")
# 异常检测
anomalies = analyzer.detect_anomalies()
for a in anomalies:
print(f"[{a.severity.value}] {a.message}")
# 性能评分（S/A/B/C/D/F 等级）
score = analyzer.score()
print(f"性能等级: {score.grade} ({score.total}/100)")
# 生成 HTML 报告（带图表）
analyzer.generate_report("report.html", include_charts=True)
```
**性能指标采集速度**：
| 指标 | 命令 | 耗时 | 建议 |
|------|------|------|------|
| FPS | `hidumper -s RenderService -a fps` | ~0.3s | ✅ 推荐 |
| CPU | `hidumper --cpuusage` | ~0.3s | ✅ 推荐 |
| 内存(指定PID) | `hidumper --mem ` | ~1.5s | ✅ 指定 package |
| 内存(全系统) | `hidumper --mem` | ~40s | ❌ 不推荐 |
| 卡顿 | `hidumper -s RenderService -a hitchs` | ~0.2s | ✅ 推荐 |
| CPU温度 | `hidumper -s ThermalService -a '-t'` | ~0.5s | ✅ 推荐 |
| 内存使用率 | `cat /proc/meminfo` | ~0.2s | ✅ 推荐 |
> 💡 **性能提示**: 设置 `package` 参数可将内存采集从 40 秒降至 1-2 秒！
### 4. 智能等待条件 🆕
更丰富的控件等待条件：
```python
# 等待控件可点击
d(text="按钮").wait_clickable(timeout=10)
# 等待控件启用
d(text="输入框").wait_enabled(timeout=5)
# 自定义等待条件
d(text="列表").wait_until(lambda el: el.info["scrollable"], timeout=10)
```
### 5. 视觉定位能力
```python
# 图像匹配点击（支持多尺度）
ok = d.click_image("target.png", threshold=0.88)
# 找色点击（RGB 容差匹配）
d.click_color((255, 0, 0), tolerance=12)
# 限制区域找色
d.click_color((0, 160, 255), tolerance=10, region=(100, 400, 600, 1200))
```
### 6. 后台 Watcher 自动处理弹窗
```python
# 自动处理常见弹窗
d.watcher("ad").when_xpath('//*[@text="跳过"]').click()
d.watcher("ok").when(text="确定").click()
d.watcher.start(interval=0.3)
# 主流程执行
d.start_app("com.example.app")
d.watcher.stop()
```
### 7. 模糊匹配选择器
```python
# 子串匹配
d(textContains="登").click()
# 正则匹配
d(textMatches=r"^\d+条$").click()
# 资源 ID 模糊匹配
d(resourceIdContains="entry", type="Button").click()
```
***
## 🔄 从 uiautomator2 无缝迁移
如果你熟悉 Android 的 `uiautomator2`，**零学习成本**直接上手：
```python
# uiautomator2 写法
from uiautomator2 import Device
d = Device()
d(text="精选").click()
d.swipe(0.5, 0.8, 0.5, 0.2)
# HMNextAuto 写法（完全一致！）
from hmnextauto.driver import Driver
d = Driver()
d(text="精选").click()
d.swipe(0.5, 0.8, 0.5, 0.2)
```
***
## 📚 API 速查
> 💡 **详细 API 文档**: [docs/API.md](docs/API.md) - 完整的 API 文档，包含所有功能说明和示例代码
### App 管理
```python
d.install_app("demo.hap") # 安装应用
d.uninstall_app("com.example.app") # 卸载应用
d.start_app("com.example.app") # 启动应用
d.stop_app("com.example.app") # 停止应用
d.clear_app("com.example.app") # 清除数据
d.start_app_by_name("微信") # 用应用名启动
d.force_start_app("com.example.app") # 强制启动（回桌面+停+启）
```
### 设备操作
```python
d.press_home() # Home 键
d.press_back() # 返回键
d.screen_on() # 亮屏
d.screen_off() # 息屏
d.unlock() # 解锁
d.open_url("https://baidu.com") # 打开 URL
d.screenshot("screen.png") # 截图
```
### 控件操作
```python
d(text="确定").click() # 点击
d(text="确定").click_if_exists() # 存在才点击
d(text="输入框").input_text("hello") # 输入文本
d(text="输入框").clear_text() # 清除文本
d(type="Button").count # 控件数量
d(text="按钮").info # 控件信息
d(text="列表").scroll.to(text="目标") # 滚动查找
```
### 手势操作
```python
d.click(0.5, 0.5) # 单击（支持百分比坐标）
d.double_click(0.5, 0.5) # 双击
d.long_click(0.5, 0.5) # 长按
d.swipe(0.5, 0.8, 0.5, 0.4) # 滑动
d.swipe_ext("up", scale=0.8) # 方向滑动
d.gesture.start(100, 200).move(300, 400).action() # 自定义手势
```
### 录屏
```python
# 推荐方式（自动清理资源）
with d.screenrecord.start("test.mp4"):
d(text="按钮").click()
```
***
## 🔍 UI Inspector 工具
配合 **uiautodev** 可视化查看控件树：
```bash
pip install "uiautodev[harmony]"
uiauto.dev
# 打开浏览器访问 http://localhost:20242
```
功能特性：
- 实时查看控件树层级
- 自动生成 XPath
- 查看控件属性详情
项目地址：
***
## 🎯 应用场景
| 场景 | 说明 |
| --------- | --------- |
| App 自动化测试 | 功能测试、回归测试 |
| 性能测试 | 配合录屏分析 |
| 自动化运营 | 批量操作脚本 |
| UI 截图对比 | 视觉回归测试 |
| 兼容性测试 | 多设备并行 |
***
## ❓ 常见问题
### Q: 找不到设备？
确保已开启 USB 调试，运行 `hdc list targets` 确认连接。
### Q: pip 安装失败？
尝试使用镜像：
```bash
pip install -U hmnextauto -i https://pypi.tuna.tsinghua.edu.cn/simple
```
### Q: 图像匹配不准确？
调整 `threshold` 参数（默认 0.85），或使用更高分辨率的模板图片。
### Q: 如何连接远程设备？
```bash
export HDC_SERVER_HOST=192.168.1.100
export HDC_SERVER_PORT=8710
```
### Q: 控件找不到？
使用 UI Inspector 工具查看控件属性，确认选择器是否正确。
### Q: 如何使用 OCR 文字识别？
OCR 功能需要额外安装依赖：
```bash
pip install hmnextauto[ocr]
```
使用示例：
```python
# 识别屏幕所有文字
results = d.ocr.read()
# 查找文字位置
pos = d.ocr.find_text("登录")
# 点击文字
d.ocr.click_text("确定")
# 等待文字出现
d.ocr.wait_text("加载完成", timeout=30)
```
***
## 📅 更新日志
| 版本 | 日期 | 主要更新 |
| ------ | ---------- | ---------------------------------- |
| v1.7.0 | 2026-05-06 | 新增 CPU 温度、内存使用率指标，报告模板支持新指标展示 |
| v1.6.1 | 2026-05-06 | 性能监控优化：并行采集、内存采集提速 20 倍（指定 PID） |
| v1.6.0 | 2026-05-06 | 新增性能数据分析工具（异常检测、评分、HTML 报告） |
| v1.5.0 | 2026-05-06 | 新增 OCR 文字识别功能（可选依赖） |
| v1.4.0 | 2026-05-03 | 新增全局隐式等待 `implicitly_wait`，Settings 配置管理 |
| v1.3.0 | 2026-04-30 | 新增通知栏操作、XPath 多元素操作、性能监控、智能等待条件 |
| v1.2.0 | 2026-04-29 | 升级 uitest\_agent v1.2.2，统一调用逻辑 |
| v1.1.0 | 2026-04-24 | 新增视觉定位功能（多尺度模板匹配、找色点击） |
| v1.0.5 | 2026-04-23 | XPath wait/wait\_gone 方法 |
| v1.0.0 | 2026-04-20 | 首次发布，基于原 hmdriver2 重构 |
***
## 💡 未来规划
- [ ] 断言/验证机制
- [ ] 元素截图/高亮
- [ ] 多设备并行支持
- [ ] 测试报告生成
***
## 🤝 参与贡献
欢迎提交 Issue 和 Pull Request！
- 🐛 [提交 Issue](https://github.com/ziguiway/HMNextAuto/issues)
- 📖 [贡献指南](CONTRIBUTING.md)
***
## 🙏 致谢
感谢原项目作者 [@codematrixer](https://github.com/codematrixer) 提供的优秀基础框架！
***
## 📄 License
[MIT License](LICENSE)
***
如果这个项目对你有帮助，请给一个 ⭐️ Star 支持一下！