单元测试触摸手势:hyprgrass MockGestureManager测试方案实战
单元测试触摸手势:hyprgrass MockGestureManager测试方案实战
hyprgrass 是一个为 Hyprland 提供触摸手势功能的插件,支持工作区切换、边缘滑动、三指手势、捏合缩放等。而它质量稳定的关键之一,就是一套基于 MockGestureManager 的单元测试方案:用"模拟手势管理器"代替真实的 Hyprland 环境,把每一次触摸按下、移动、抬起变成可脚本化的数据序列,再逐事件断言。本文带你读懂这套 hyprgrass 触摸手势单元测试方案的完整思路与运行方法。
为什么要给触摸手势做单元测试?
触摸手势的行为非常"微妙":手指移动多少像素才算滑动手势?长按多久才生效?三指同时落下后事件该转发给窗口还是拦截?这些边界规则一旦出错,用户轻点一下可能整个触控都"失灵"。
手动在真实桌面上反复测试成本高且不可重复,因此 src/gestures/test/README.md 中说明,这套测试的核心目标是:用于验证 wf-touch 手势库的行为(Used for testing behavior of wf-touch),让每次代码改动都能自动回归验证。
难点在于:真实的手势管理器(见 src/GestureManager.hpp)深度依赖 Hyprland 内部能力——向窗口发送取消事件、读取配置项、启动长按定时器……没有显示器和 Wayland 环境根本跑不起来。
测试方案架构:一个目录、五个文件
整个测试方案集中在 src/gestures/test/ 目录,结构极其精简:
| 文件 | 职责 |
|---|---|
| MockGestureManager.hpp | Mock 手势管理器类声明与工厂方法 |
| MockGestureManager.cpp | Mock 类的具体实现,记录"发生了什么" |
| CoutLogger.hpp | 把调试日志输出到终端的简单 Logger |
| test.cpp | 全部 26 个 doctest 测试用例 |
| test/meson.build | Meson 构建与测试注册配置 |
方案的关键设计:真实插件与 Mock 类共同实现同一个接口 IGestureManager(定义于 src/gestures/Gestures.hpp)。
wf-touch 手势库(被测对象)
↓ 调用
IGestureManager 接口
├── GestureManager ← 真实实现,挂在 Hyprland 里
└── CMockGestureManager ← 测试替身,记录调用而不依赖 WM
手势识别的算法本体(阈值判断、进度计算等)在基类中,测试时原封不动地走真实代码;Mock 只替换"触发后往哪送"的部分。这就是测试能跑得又快又干净的根源。
MockGestureManager:模拟手势管理器如何工作
4 个工厂方法,覆盖 4 种处理器行为
MockGestureManager.hpp 提供了 4 个静态工厂方法,一行代码就能构造出不同的"被测对象人格":
| 工厂方法 | 行为 | 典型用途 |
|---|---|---|
newDragHandler() |
只处理拖拽手势 | 验证滑动拖拽的启动/结束 |
newCompletedGestureOnlyHandler() |
只响应完整手势 | 验证"松手后触发"型手势 |
newBothHandler() |
完整手势与拖拽都响应 | 验证二者的优先级 |
newNonConsumingHandler() |
执行手势但不消费事件 | 验证"非消费"手势不拦截窗口触摸 |
5 个可观察状态标志
Mock 类把每个回调"翻译"成布尔标志,断言时一目了然:
bool triggered; // 完整手势是否触发
bool cancelled; // 手势是否被取消
bool dragEnded; // 拖拽是否结束
bool sentWindowCancel; // 是否向窗口发送了取消事件
Mock 内部还预设了一块 1920×1080 的"虚拟屏幕",边缘滑动手势测试甚至可以改 mon_offset 模拟多显示器偏移场景——全程无需任何真实设备。
test.cpp:把触摸"脚本化"的 doctest 测试
事件脚本:触摸与断言交错排列
test.cpp 中最精妙的设计是 TouchEvent 类型——一个 std::variant,列表里既能放触摸事件,也能放断言点:
const std::vector<TouchEvent> events{
Ev{wf::touch::EVENT_TYPE_TOUCH_DOWN, 100, 0, {450, 290}}, // 手指0按下
Ev{wf::touch::EVENT_TYPE_TOUCH_DOWN, 100, 1, {500, 300}}, // 手指1按下
Ev{wf::touch::EVENT_TYPE_TOUCH_DOWN, 100, 2, {550, 290}}, // 手指2按下
ExpectResult{ExpectResultType::NOT_SENT_WINDOW_CANCEL}, // 此刻不应拦截窗口
Ev{wf::touch::EVENT_TYPE_MOTION, 200, 0, {0, 290}}, // 手指0大幅左移
ExpectResult{ExpectResultType::SENT_WINDOW_CANCEL}, // 此刻应已拦截
};
ProcessEvents(gm, {.type = ExpectResultType::DRAG_TRIGGERED}, events);
读起来像一段分镜脚本:"三指落下 → 检查没拦截 → 手指大幅移动 → 检查已拦截 → 最终断言拖拽被触发"。ProcessEvents 会在每个事件后自动检查前置状态(未触发、未取消),保证脚本步步为营。
9 种预期结果
断言被抽象成 ExpectResultType 枚举,共 9 种,覆盖手势全生命周期:COMPLETED(完成)、COMPLETED_NON_CONSUMING(非消费完成)、DRAG_TRIGGERED(拖拽开始)、DRAG_ENDED(拖拽结束)、CANCELLED(被取消)、SENT_WINDOW_CANCEL / NOT_SENT_WINDOW_CANCEL(是否拦截窗口)、CHECK_PROGRESS(检查手势进度值)、NOTHING_HAPPENED(无反应)。
26 个测试用例:覆盖全部手势类型
测试用例围绕插件支持的每一种手势展开,正例、反例、边界值一个不落:
| 手势类型 | 测试重点(节选) |
|---|---|
| 三指滑动(Swipe) | 超过阈值启动拖拽、松手后完成、误拖取消、完成优先于拖拽 |
| 多指轻点(Multi-finger Tap) | 正常触发、超时取消、移动过多取消(含向上方向)、非消费模式 |
| 长按(Long Press) | 按住 400ms 后开始拖拽、松手过短被取消、移动过多加上/减方向都验证 |
| 边缘滑动(Edge Swipe) | 边缘内 10px 生效、自定义边距、非边缘起点在结束时被拒绝、多显示器偏移 |
| 捏合(Pinch) | 捏合内/外的完整拖拽、完成手势、优先级与非消费模式 |
其中几个细节值得新手学习:
- 方向对称性:像"移动过多"这类取消逻辑,专门用 -y 方向(向上)再测一遍,因为
delta.x为正数时的表达式可能对负方向失效; - 浮点数断言:进度检查用
std::abs(got - expect.progress) < 1e-5的容差比较,规避浮点精度陷阱; - 有意识标记失效用例:多指手势第一个用例标注了
doctest::should_fail(),说明"3指落下即拦截窗口"的功能已移除、可能恢复,测试先保留占位——这是很好的工程习惯。
手势阈值常量(滑动阈值 150px、容错 100px 等)统一定义在 src/gestures/Shared.hpp,测试直接引用,保证测试与实现使用同一份参数。
如何构建并运行 hyprgrass 单元测试
一键构建步骤
测试由 Meson 构建系统驱动,meson_options.txt 中定义了 tests 选项(默认 auto:找到 doctest 就启用)。构建并运行只需三行:
git clone https://gitcode.com/gh_mirrors/hy/hyprgrass
cd hyprgrass
meson setup build -Dtests=enabled
ninja -C build test
运行后 Meson 会执行注册在 src/gestures/test/meson.build 中的 test gestures 测试(编译产物为 test-gestures 可执行文件)。想单独查看某个用例的结果,可以追加 -v 参数。
Nix 用户:开箱即用的测试包
如果用 Nix 构建,flake.nix 提供了专门的测试包 hyprgrassWithTests,它把 nix/default.nix 中的 runTests 打开并开启 doCheck,nix build .#hyprgrassWithTests 会在构建期自动跑完全部单元测试。
这套测试方案的 3 个可借鉴亮点
- 接口隔离 + Mock 替身:
IGestureManager让手势算法与窗口管理器彻底解耦,测试零硬件依赖,毫秒级跑完 26 个用例; - 事件脚本 + 断言内联:用
std::variant把"操作"和"检查"混排在一个列表里,测试即场景描述,可读性远超层层嵌套的EXPECT; - 正例反例成对出现:每个手势都同时覆盖"该触发"与"该取消"(超时、移过多、起点不符),边界行为回归有明确保障。
下次当你面对"逻辑正确但依赖重量级环境"的模块时,不妨照搬 hyprgrass 的思路:抽一个最小接口,写一个会"做笔记"的 Mock,再把手势/事件流写成脚本,你的单元测试也能既快又稳。🎯