test: 建立测试体系 - Vitest 单元+组件测试与测试策略文档

docs/测试策略与方案.md

@@ -0,0 +1,123 @@
+# 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 + 测试范围）
+src/renderer/src/
+├── test/setup.ts                     # 全局 setup：jest-dom 匹配器 + 自动 cleanup
+├── diff/
+│   ├── diffEngine.test.ts            # diff 引擎单元测试
+│   └── report.test.ts                # 报告生成测试
+└── __tests__/
+    └── App.test.tsx                  # 应用冒烟测试
+```
+
+> 约定：测试文件与被测文件同目录（`*.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. 运行命令
+
+```bash
+npm test          # 运行全部测试（CI / 提交前）
+npm run test:watch # 监听模式，开发中用
+```
+
+---
+
+## 7. 质量门禁
+
+提交与推送前 **必须全部通过**：
+
+```bash
+npm run typecheck
+npm test
+npm run build
+```
+
+任一失败即禁止提交；修复通过后再提交发布。
+
+---
+
+## 8. 覆盖率目标（演进基线）
+
+| 模块 | 目标 |
+| --- | --- |
+| 逻辑层（diff / report） | ≥ 80% 行覆盖（当前以核心用例保证关键路径） |
+| 组件层（App） | 覆盖主流程空态与关键交互 |
+
+> 具体门槛随各模块成熟度逐步收紧；当前先保证**关键路径断言完整**。
+
+---
+
+## 9. 演进方向（后续迭代）
+
+- 接入 Playwright 对打包后的 Electron 应用做端到端验收
+- 对 IPC 层（open / decode / save-report）补充集成测试
+- 大文件性能基准测试（虚拟滚动落地后）
+
+---
+
+© 2026 MetonaTeam · thzxx · DiffLens