单元测试触摸手势:hyprgrass MockGestureManager测试方案实战

原创2026-11-16 14:04:531,612 阅读

单元测试触摸手势: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 个可借鉴亮点

  1. 接口隔离 + Mock 替身:IGestureManager 让手势算法与窗口管理器彻底解耦,测试零硬件依赖,毫秒级跑完 26 个用例;
  2. 事件脚本 + 断言内联:用 std::variant 把"操作"和"检查"混排在一个列表里,测试即场景描述,可读性远超层层嵌套的 EXPECT;
  3. 正例反例成对出现:每个手势都同时覆盖"该触发"与"该取消"(超时、移过多、起点不符),边界行为回归有明确保障。

下次当你面对"逻辑正确但依赖重量级环境"的模块时,不妨照搬 hyprgrass 的思路:抽一个最小接口,写一个会"做笔记"的 Mock,再把手势/事件流写成脚本,你的单元测试也能既快又稳。🎯

登录后查看全文
hyprgrass