DiffLens/docs/测试策略与方案.md

DiffLens 测试策略与方案

规范化 DiffLens 的测试体系：分层、选型、覆盖重点、运行与质量门禁。 配套文档：《应用开发与版本迭代规范》

---

1. 目标与原则

• 保障正确性：核心 diff 算法与报告生成必须被单元测试覆盖，防止回归
• 可回归：每次迭代（0.y.z）在前都能稳定跑通测试
• 简单优先：不做为测而测，优先覆盖纯逻辑与高风险模块
• 门禁前置：npm test 纳入提交/推送前的强制检查

---

2. 测试分层

层级	覆盖对象	工具
单元测试（UT）	纯逻辑：diff 引擎、报告生成器	Vitest
组件测试	React 组件：应用空态、工具栏交互	Vitest + Testing Library
集成（演进中）	Electron IPC / 多进程协作	预留 Playwright 或 Electron 测试

现阶段以单元 + 组件为主，覆盖最核心、最易回归的部分。

---

3. 技术栈

用途	选型
框架	Vitest（与 Vite 生态一致，快）
环境	jsdom
React 测试	@testing-library/react
断言扩展	@testing-library/jest-dom
未来 E2E	Playwright（预留，暂不引入）

---

4. 目录结构

vitest.config.ts                      # Vitest 配置（jsdom + 测试范围 + 覆盖率 80% 硬门禁）
src/renderer/src/
├── test/
│   └── setup.ts                      # 全局 setup：jest-dom 匹配器 + 自动 cleanup
├── diff/
│   ├── diffEngine.test.ts            # diff 引擎单元测试
│   ├── report.test.ts                # 报告生成测试
│   └── textUtils.test.ts             # 文本扩展名与行数统计测试
├── components/
│   ├── ContextMenu.test.tsx          # 右键菜单（含边缘防溢出）
│   ├── DiffView.test.tsx             # 对比视图（渲染/滚动同步/右键/拖放）
│   ├── TextInputModal.test.tsx       # 粘贴文本弹窗
│   └── Toolbar.test.tsx              # 工具栏（选项/导航/导出菜单）
└── __tests__/
    ├── App.test.tsx                  # 应用集成级测试（加载/拖拽/粘贴/导出/容错）
    └── main.test.ts                  # 入口挂载冒烟测试

约定：测试文件与被测文件同目录（*.test.ts(x)），或集中放各模块下 __tests__。

---

5. 覆盖重点与用例

5.1 diff 引擎（diffEngine.ts）— 最高优先级

• 空文本 / 空对非空（全新增）
• 完全一致 → 全部 unchanged，无差异
• 行级：新增、删除（含左/右行号、空槽 lineNo 为 null）
• 词级：同一删除/新增配对为 modified 并产生左右 segs
• 忽略选项：ignoreCase、trimWhitespace 生效与关闭
• 行切分：结尾换行不产生多余空行

5.2 报告生成（report.ts）

• HTML：输出合法文档、含文件名/统计/类型高亮语义
• 纯文本：含增删改标记（+ -）
• Markdown：表格化、管道符转义保持表格结构
• 格式分发与扩展名映射（REPORT_EXT）

5.3 应用冒烟（App.tsx）

• 渲染应用名 DiffLens
• 未加载文件时展示左右空态面板
• 未加载文件时不显示导出入口（导出仅在加载后可用）

---

6. 运行命令

npm test          # 运行全部测试（CI / 提交前）
npm run test:watch # 监听模式，开发中用

---

7. 质量门禁

提交与推送前 必须全部通过：

npm run typecheck
npm test
npm run build

任一失败即禁止提交；修复通过后再提交发布。

---

8. 覆盖率目标（演进基线）

模块	目标
逻辑层（diff / report / textUtils）	行覆盖 ≥ 80%
组件层（components / App）	覆盖主流程空态与关键交互

80% 四项阈值（statements / branches / functions / lines）已写入 vitest.config.ts 的 coverage.thresholds，作为 CI 硬门禁强制执行，未达标即测试失败。

---

9. 演进方向（后续迭代）

• 接入 Playwright 对打包后的 Electron 应用做端到端验收
• 对 IPC 层（open / decode / save-report）补充集成测试
• 大文件性能基准测试（虚拟滚动落地后）

---

© 2026 MetonaTeam · thzxx · DiffLens