鸿蒙原生软件开发之UI自动化测试

界面回归靠肉眼截图？

别再用肉眼审 UI

让屏幕自己说话

鸿蒙 UI 自动化测试基建 · 一次投入，长期复利

PART 01

为什么非搭不可

三个痛点

PART 02

搭起来长啥样

六步路径

PART 03

难在哪

四个坑

PART 04

难搭却值得

钻石与同源

PART 05

落地骨架

代码与对比

PART 06

五条经验

给开发者

PART 07

易错清单

自查三步

PART ///

写在最后

收束

01

PART

为什么非搭不可：三个扎心的痛点

PAIN POINTS · 测试基建

主观且不可重复：手动操作加截图对比，同一个操作两次结果「看起来差不多」，可你没法向同事证明「真的好了」。

成本随功能线性膨胀：每天十几个 commit 的节奏下，全量回归越来越贵，最后只能保主路径，边缘场景直接漏测。

单测根本够不着界面：src/test 里的单元测试测的是纯逻辑——markdown 解析、filter 构造；可界面显示、滚动位置、键盘行为，必须真机才验得了。

02

PART

搭起来长啥样：一套命令跑完全部 UI 用例

BLUEPRINT · 搭建路径

建了 ohosTest 测试工程：UiTestEnv（环境初始化）、UiTestUtil（公共操作：点击 / 滑动 / 等待）、五个页面对象、六个测试套件（含资源页套件）。

聚合入口 List.test.ets，一条命令跑完全部 UI 用例。

当天下午，每个界面修复都用 hdc shell uitest dumpLayout 读屏幕真实文本加坐标验证——从「我看图觉得好了」变成「屏幕文本证明好了」。

建立 ohosTest 测试模块（entry/src/ohosTest/）

引入 @kit.TestKit：Driver.create() 获取 UI 驱动

抽象 UiTestEnv（启动 / 进入指定页面 / 清理）

抽象 UiTestUtil（公共操作：clickByText / swipe / 等待元素）

按页面建页面对象（MemoListPage / MemoDetailPage / SearchPage / ResourcePage…）

每个页面对象暴露「断言方法」（expect 某文本可见、某坐标存在）

03

PART

难在哪：四个坑，我替你踩了一遍

PITFALLS · 四个难点

难点一：TestKit API 不熟

难点二：页面对象抽象粒度

难点三：注入与真机手感有差异

难点四：等待与稳定性

04

PART

为什么难搭却值得：地基是钻石，用例是砖头

WHY IT PAYS · 复利本质

TestKit 文档少、示例少 → 摸 API 语义耗时（Driver.create / ON.text / 等待）

页面对象抽象需要「先想清楚分层」 → 前期投入高于写一条用例

注入与真机差异 → 选型时就要考虑「被测能力是否可注入」

UI 测试工具 = 排查工具：

　　pytest 用 dumpLayout 断言屏幕文本 → 排查时也用 dumpLayout 看屏幕真相

　　pytest 用 uiInput 注入操作 → 排查时也用 uiInput 复现

一次基建，测试与排障双复用 —— 这才是「复利」的真正来源

05

PART

落地骨架：代码、API、与一张对比表

BLUEPRINT · 落地代码

// UiTestUtil：公共操作（点击文本 / 滑动 / 等待元素）

export class UiTestUtil {

　　static async clickByText(driver: Driver, text: string): Promise<void> {

　　　　await driver.findComponent(ON.text(text)).click();

　　}

　　static async waitForText(driver: Driver, text: string, timeout = 3000): Promise<void> {

　　　　// 条件等待：元素出现才继续，避免固定 sleep

　　}

}

// 页面对象：一个页面一个类，暴露断言方法

export class MemoDetailPage {

　　static async expectTitle(driver: Driver, title: string): Promise<void> {

　　　　await driver.findComponent(ON.text(title)).assertExist();

　　}

}

// 套件聚合：List.test.ets 一条命令跑全部

// （5 个页面对象 + 6 个套件，全部注册进 List.test.ets）

// 反模式：await sleep(2000)（动画 / 加载慢时偶发失败）

// 正模式：条件等待（轮询直到元素出现或超时）

await driver.findComponent(ON.text('目标文本'))

　　.waitUntil(async (comp) => await comp.isExist(), 3000);

06

PART

给鸿蒙开发者的五条经验

LESSONS · 五条经验

测试基建「地基重、用例轻」：环境、页面对象、公共操作一次性搭好，之后每条用例都是廉价增量——别让每条用例自己摸 API。

测试工具与排障工具同源：dumpLayout 既能断言屏幕文本，也能排查「界面到底显示了什么」；uiInput 既能自动化操作，也能复现用户路径。搭基建时优先选「排障也用得上」的工具能力。

条件等待大于固定 sleep：UI 用例的偶发失败八成来自等待不足——用「轮询直到元素出现」替代「睡两秒」。

注入兼容性影响选型：被测能力（尤其手势）要确认对 uiInput 注入是否响应——onTouch方案对注入响应良好、PanGesture 可能失灵，选型时就把可测试性算进去。

断言用「屏幕真实文本」而非「肉眼截图」：dumpLayout 的文本加坐标是确定性的；截图对比主观且没法自动化。

07

PART

易错点清单与自查三步

CHECKLIST · 避坑

① 用例不稳定？ → 等待改条件等待（轮询元素出现）

② 页面改版就崩？ → 选择器收进页面对象（页面对象分层）

③ 断言主观？ → 改 dumpLayout 文本断言（确定性）

# UI 测试编译（ohosTest 模块）

./hvigorw assembleHap --mode module -p module=entry@ohosTest --no-daemon

# 运行测试套件（src/test 单测）

./hvigorw test --mode module -p product=default --no-daemon

# 排障 / 断言双用：读屏幕真实文本

hdc shell uitest dumpLayout

# 注入操作

hdc shell uitest uiInput click 550 600

///

LAST

写在最后

WRAP-UP · 收束