Pi-Harness 质量工程实践:Vitest 单测、Playwright E2E 与质量门禁三层测试体系

原创2026-10-18 20:19:362,164 阅读

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 应用。

Pi-Harness 工作区测试界面截图

上图为 E2E 测试实际打开的 Pi-Harness 工作区界面

隔离环境启动:fixtures 是关键

所有 E2E 用例共享 e2e/fixtures.ts 提供的统一 fixture,它做了几件重要的事:

  1. 隔离数据:每次测试用临时目录作为工作区和用户数据,测试结束后清理
  2. Mock Pi:把 fixtures/mock-pi 复制到隔离目录,作为假的 Pi 配置目录,让应用无需真实安装 Pi 也能完整运行(详见 fixtures/README.md)
  3. 启动真实 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 应用来说,宁可慢一点,也不要不可复现的失败。

Pi-Harness 工具 Harness 控制台界面

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,发布流程被阻断。

Pi-Harness 设置界面测试截图

设置页是门禁与 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 落盘——测试不再只是红绿信号,而是可追溯的工程资产。

关键路径导航:

登录后查看全文
pi-harness