Pi-Harness 质量工程实践:Vitest 单测、Playwright E2E 与质量门禁三层测试体系
Pi-Harness 质量工程实践:Vitest 单测、Playwright E2E 与质量门禁三层测试体系
Pi-Harness 是 Pi Coding Agent 的运维超集,为 Agent 提供可观测性、治理、故障恢复、评估与多 Agent 编排。作为一个 Electron 桌面应用,它的代码质量由一套三层测试体系保障:Vitest 单元测试、Playwright E2E 端到端测试,以及一键质量门禁。本文带你快速看懂这套体系是如何运转的。
第一层:Vitest 单元测试——秒级的质量底线
Pi-Harness 的单元测试全部基于 Vitest,测试文件与源码同目录放置,命名为 *.test.ts,在 src/ 目录下约有 200 个测试文件,覆盖了主进程服务、共享逻辑和渲染层组件。
单元测试的配置集中在 vitest.config.ts:
- 使用
jsdom环境,可以挂载 Vue 组件做渲染断言 - 通过别名
@renderer和@shared指向渲染层与共享代码 - 测试文件匹配规则为
src/**/*.{test,spec}.{ts,tsx}
以 API Key 解析规则为例,api-key-parse.test.ts 验证了环境变量引用、密钥链命令、明文字面量三种 wire 格式各自的解析行为。这类测试不需要启动应用,pnpm test 即可秒级完成,是每次提交前最快速的质量底线。
pnpm test # 等价于 pnpm run test:unit → vitest run
pnpm test:watch # 开发时监听模式
第二层:Playwright E2E——像真实用户一样操作应用
E2E 层位于 e2e/ 目录,共 40 个 spec 文件,覆盖工作区、Git、模型管理、主题、性能等几乎全部核心功能。与"伪前端"不同,它启动的是真实编译后的 Electron 应用。
上图为 E2E 测试实际打开的 Pi-Harness 工作区界面
隔离环境启动:fixtures 是关键
所有 E2E 用例共享 e2e/fixtures.ts 提供的统一 fixture,它做了几件重要的事:
- 隔离数据:每次测试用临时目录作为工作区和用户数据,测试结束后清理
- Mock Pi:把 fixtures/mock-pi 复制到隔离目录,作为假的 Pi 配置目录,让应用无需真实安装 Pi 也能完整运行(详见 fixtures/README.md)
- 启动真实 Electron:
electron.launch()拉起编译产物out/main/index.js,并记录启动耗时供性能断言使用
安全边界也是被测对象
production-boundary.spec.ts 是 E2E 里最有代表性的一条:它验证打包后的应用 contextIsolation 为 true、nodeIntegration 为 false、渲染进程无法访问 require——确保桌面应用的进程隔离边界没有退化。
串行执行,稳定优先
playwright.config.ts 的配置体现了"稳定优先"的策略:workers: 1 单进程串行、retries: 0 不重试、单用例 90 秒超时。对 Electron 应用来说,宁可慢一点,也不要不可复现的失败。
Harness 控制台是 E2E 重点覆盖的界面之一
第三层:质量门禁——一条命令判定能否发布
前两层回答"代码对不对",质量门禁回答"这个版本能不能发"。入口是 scripts/quality-gate.mjs,由 pnpm quality 触发,它会按固定顺序执行全部检查,任何一项失败即整体失败:
| 顺序 | 检查项 | 说明 |
|---|---|---|
| 1 | typecheck / lint |
类型检查与 ESLint 代码规范 |
| 2 | test |
全量 Vitest 单元测试 |
| 3 | compile |
完整编译 Electron 应用 |
| 4 | dependency-licenses / dependency-audit |
依赖许可证与高危漏洞审计 |
| 5 | performance-benchmark |
性能基准测试 |
| 6 | core-e2e |
核心 E2E 用例(含首次消息、生产边界等 5 个) |
| 7 | compile-nomascot + nomascot-e2e |
无吉祥物变体的编译与回归 |
| 8 | package + artifact-integrity + packaged-e2e |
加 --package 时验证真实安装包 |
门禁还会计算源码指纹并做 source-stability 校验,防止检查过程中源码被意外修改。每轮检查的日志、耗时都写入 out/quality/ 目录,并生成 JSON + Markdown 报告。
多平台汇总判定
单个平台的报告还不够。scripts/release-readiness.mjs 会汇总 darwin-arm64、darwin-x64、win32-x64、linux-x64 四个平台的报告,核对版本号与源码指纹完全一致、16 项必查项全部 PASS 后,才输出最终的 READY 结论;否则为 NOT_READY,发布流程被阻断。
设置页是门禁与 E2E 常规覆盖的目标页面之一
性能基准:质量不只是"不报错"
质量门禁中的 performance-benchmark 对应 benchmarks/quality.test.ts,它用程序化生成 1 万、5 万、10 万条会话的语料,对通用会话服务的同步、搜索、恢复耗时以及项目架构扫描做三轮可复现测量,结果连同环境信息(CPU、Node 版本)一起落盘到 out/quality/benchmark.json,配置见 quality-benchmark.config.ts。
配合 quality-performance.spec.ts,E2E 层还会记录全新配置的首次启动耗时、渲染器重载耗时和架构图生成延迟——性能数据与功能断言一样,是被持续跟踪的质量指标。
上手运行:常用命令速查
pnpm test # 运行 Vitest 单元测试
pnpm typecheck # TypeScript 类型检查
pnpm lint # ESLint 代码规范检查
pnpm test:e2e # 先编译再运行 Playwright E2E
pnpm benchmark:quality # 单独运行性能基准
pnpm quality # 完整质量门禁
pnpm quality:release # 汇总多平台报告,判定发布就绪
小结
Pi-Harness 的测试体系可以概括为三道防线:
- Vitest 单测:约 200 个测试文件与源码同目录,守护每个函数和组件的正确性
- Playwright E2E:40 个 spec 启动真实 Electron 应用,用隔离 fixture 和 mock Pi 目录复现完整用户路径
- 质量门禁:
pnpm quality一条命令串联静态检查、测试、审计、性能与打包验证,多平台汇总后才敢盖章READY
对新手来说,最值得借鉴的是它的"报告化"思路:每个检查项都有名称、状态、耗时和日志,最终以结构化 JSON 落盘——测试不再只是红绿信号,而是可追溯的工程资产。
关键路径导航:
- 单测配置:vitest.config.ts
- E2E 配置与 fixture:playwright.config.ts、e2e/fixtures.ts
- 质量门禁:scripts/quality-gate.mjs、scripts/release-readiness.mjs
- 性能基准:benchmarks/quality.test.ts
- 测试用 mock 数据:fixtures/README.md


