lolPing 桌面应用怎么测：测试与 CI 实践完整清单-开发者社区

【免费下载链接】lolPing

League of Legends ping wheel for your Windows desktop. Hold Alt, drag, and ping anywhere, with the original animations and sounds.

项目地址：https://gitcode.com/gh_mirrors/lo/lolPing

点击查看免费下载

lolPing 是一个给 Windows 和 macOS 桌面用的英雄联盟风格 ping 轮盘：按住 Alt 拖拽、松手即可在任何位置发出 ping，带有原汁原味的动画和音效。这类应用有个特殊的测试难题——它要监听全局鼠标键盘、画透明悬浮窗，很难直接用 UI 自动化碰它。这个项目用"纯逻辑抽离 + 协议模拟 + 假进程替身"的组合拳，把大部分行为变成了不碰 UI 就能跑的单测，再由 GitHub Actions 在 Windows 和 macOS 双平台把关。下面是一份完整的清单式盘点。

一、测试分层：一个应用，三套测试

lolPing 的代码分为两层：Electron（TypeScript）负责窗口、悬浮层和房间协议；C++ 进程 hook-helper 负责底层的输入钩子（Windows 全局钩子 / macOS event tap）。对应地，测试也分三层，全部由 vitest.config.ts 和 run.mjs 驱动：

层	跑什么	命令	位置
C++ 纯逻辑	手势状态机`Decision`	`npm run test:helper`	helper_tests.cpp
协议集成	启动真实 helper 的`--simulate`模式，喂模拟按键	`npm test`	protocol.test.ts
TypeScript 单测	主进程、渲染层、共享模块	`npm test`	tests/

🎯 核心思路只有一句话：把"决策"从"胶水"里抽出来，测决策，不测胶水。钩子拿到按键后做什么，全部由一个纯函数状态机 decision.cpp 决定；C++ 测试直接向状态机灌入事件序列，断言它该"吞掉"哪些输入、该向 Electron 发什么事件——完全不需要真实的鼠标键盘。

二、TypeScript 测试：40+ 个文件，镜像 src 结构

测试目录 tests/ 与源码 src/ 一一对应：tests/main/对应src/main/，tests/shared/对应src/shared/。几个有代表性的做法值得借鉴：

1. 假替身（fixtures）替代真实依赖

tests/main/fixtures/ 里放着一套"替身演员"：

fake-helper.mjs：用 Node 脚本冒充 C++ helper。它能模拟三种状态——正常回显、启动即崩溃、macOS 无辅助功能权限退出。于是 inputBridge.test.ts 可以稳定复现"helper 崩溃 3 次后放弃重启""无权限时不盲目重启"这类故障恢复逻辑。
fakeSocket.ts：WebSocket 替身，测试想让它打开就打开、想断线就断线，relayConnection.test.ts 借此覆盖了 Nostr 中继的订阅、重连和回声去重。
fakeTransport.ts 与 fakeRelay.ts：把局域网 UDP 和中继网络都换成内存管道，房间加密、防重放等逻辑（如 roomCrypto.test.ts、replayGuard.test.ts）因此零真实网络。

2. 确定性三板斧：注入时间、注入随机、等待条件

以 floodGuard.test.ts 为例，时间不是Date.now()，而是外部传入的now: () => number，测试用advance(1000)手动拨快时钟，验证限流预算"随时间回血"。项目规范（AGENTS.md）明确写着：不写固定 sleep，等条件而不是等时间。

npm run typecheck # 类型检查 npm run test:helper # 构建并跑 C++ 测试 npm test # 跑全部 TypeScript 测试

3. 连 CI 脚本本身也有测试

最有意思的一条：releaseWorkflow.test.ts 直接读取 release.yml 的文本，用断言"锁死"发布流程的顺序——比如"平台 job 里绝不能出现--draft=false"、"Windows job 必须上传latest.yml和 blockmap"。工作流改错了？测试会先红给你看。

三、CI 双平台：一次推送，两道门禁

CI 定义在 ci.yml，main分支推送和每个 PR 都会触发两个并行 job：

test（windows-latest）：npm ci→typecheck→test:helper（编译 hook-helper.exe 并跑 C++ 测试，TypeScript 协议测试依赖这个产物）→npm test→npm run build与build:site，保证能打包、演示页能构建。
test-mac（macos-latest，Apple Silicon）：同样的测试链，外加dist:mac完整出包，再用codesign --verify校验签名、确认 hook-helper 是 arm64、托盘图标在位，最后把.dmg作为 artifact 保留 14 天。

两个细节很实用：macOS 上设置了CSC_FOR_PULL_REQUEST: true（arm64 未签名 app 根本启动不了，PR 上也必须做 ad-hoc 签名）；权限只给contents: read，最小化 CI 的越权能力。

四、发布流水线：测试是发布的入场券

release.yml 在推送形如v0.5.1的 tag 时触发，同样先跑test:helper和npm test，通过才允许出安装包。它的顺序被设计成"草稿发布"模式：先建 draft release → Windows 和 macOS job 分别上传安装包与latest.yml/blockmap → 最后由 publish job 转正。这样已安装应用读取更新时不会遇到"latest.yml 还没上传"的失败窗口。