feat: 解码 worker 化、Playwright E2E 测试体系与文件夹对比（0.6.0）
This commit is contained in:
+10
-6
@@ -20,7 +20,7 @@ z = 补丁版本号（Patch）
|
||||
> **`x` 永远是 `0`，永远不要提升到 `1.0.0`。**
|
||||
> 版本迭代**只允许修改 `y` 和 `z`**，`x` 保持 `0` 不变。
|
||||
|
||||
当前基线版本：**`0.5.5`**
|
||||
当前基线版本：**`0.6.0`**
|
||||
|
||||
---
|
||||
|
||||
@@ -75,8 +75,11 @@ z = 补丁版本号（Patch）
|
||||
0.5.2 ← 稳健性收尾与偏好记忆（已发布）：diff worker 运行崩溃 onerror 兜底（终止实例回退主线程同步计算，effect 取消/jobId 已推进的迟到错误不回填） · 主进程 will-navigate 导航白名单加固（仅放行回到应用首页） · nativeTheme 暗色主题（Windows 标题栏等系统控件跟随应用风格） · 比较选项与仅看差异开关持久化（localStorage 记忆用户偏好，损坏数据防御性回退默认） · 字符级降级报告选项构造与引擎降级分支对齐（补 trimWhitespace 置否）
|
||||
0.5.3 ← 稳健性补漏与偏好记忆收尾（已发布）：字符级对比少行大字符量输入改走 worker 后台计算（重输入判定补入字符量维度，行数防不住 diffChars O(ND) 耗时失控） · toast 队列化（最多 3 条堆叠、各自独立计时，二进制预警不再被行数预警顶掉） · 清空按钮二次确认（toast 提示 + 3 秒确认窗口，超时自动复位） · 窗口尺寸/位置记忆（关闭保存 bounds，启动恢复并钳制回工作区，损坏数据回退默认） · 文件对话框记忆上次打开目录 · 状态栏显示两侧行数 · 偏好读取挂载期单次化 · 主进程测试基建建立（windowState 纯逻辑模块 + vitest include 扩展至 src/main）
|
||||
0.5.4 ← 比较选项联动可视化与状态透明（已发布）：修复禁用开关零视觉反馈的样式缺陷（原 CSS 仅有 button:disabled，checkbox 禁用后外观不变，用户不知哪些可选） · 字符级开启时三个空白选项灰显勾选（循系统惯例表达“语义已包含且生效”，仅为视觉呈现不改写用户原状态，关闭字符级即复原） · 常显“已包含”徽标（原仅 hover title 可知禁用原因） · 点击被包含选项弹 toast 解释而非无反应 · 字符级因内容超限自动降级时开关旁常显“已降级”标记（状态透明）
|
||||
0.5.5 ← 字符级对比无界计算卡死修复（当前）：diffChars 携 maxEditLength=3000 封顶 Myers 迭代轮数（编辑距离超限立即放弃并降级行级，根治大字符量+大差异输入 O(ND) 无界计算导致遮罩永久卡死——实测 3 万字符全不同无上限需数十分钟） · 字符量降级阈值 20 万收紧至 3 万（双限配合将最坏耗时锁在约 2 秒，worker 内计算界面不冻结） · 重输入 worker 派发阈值随动收紧（原始字符 7500，同步快路径最坏冻结压至 0.5 秒内） · 降级提示文案改“内容或差异过大”覆盖两种降级原因 · DiffOptions 增内部测试参数 charDiffMaxEdit（测试以小阈值毫秒级构造降级场景）
|
||||
0.6.0 ← 新增功能（候选：主进程解码 worker 化 · Playwright E2E · 文件夹对比）
|
||||
0.5.5 ← 字符级对比无界计算卡死修复（已发布）：diffChars 携 maxEditLength=3000 封顶 Myers 迭代轮数（编辑距离超限立即放弃并降级行级，根治大字符量+大差异输入 O(ND) 无界计算导致遮罩永久卡死——实测 3 万字符全不同无上限需数十分钟） · 字符量降级阈值 20 万收紧至 3 万（双限配合将最坏耗时锁在约 2 秒，worker 内计算界面不冻结） · 重输入 worker 派发阈值随动收紧（原始字符 7500，同步快路径最坏冻结压至 0.5 秒内） · 降级提示文案改“内容或差异过大”覆盖两种降级原因 · DiffOptions 增内部测试参数 charDiffMaxEdit（测试以小阈值毫秒级构造降级场景）
|
||||
0.6.0 ← 解码 worker 化 · Playwright E2E · 文件夹对比（当前）：
|
||||
- 主进程解码 worker 化：≥256KB 缓冲移入 worker_threads 后台解码（GBK 纯 JS 解码大文件可达数百毫秒，不再阻塞主进程事件循环） · 解码与编码探测抽为纯逻辑模块 decode.ts（Uint8Array 入参，主进程同步路径与 worker 克隆路径共用） · worker 单例管理（崩溃拒绝在途任务并销毁重建，创建/运行失败回退主进程同步解码，行为不降级） · 构建改双入口（index + decodeWorker，iconv-lite 打包进产物） · out/main 整体 asarUnpack（Electron 的 asar 补丁不覆盖 worker 线程，unpacked 路径下无法解析 asar 内 node_modules）
|
||||
- Playwright E2E 测试体系建立：对 build 产物启动真实 Electron 验收（复用项目自带 Electron，无需下载浏览器） · 首批 11 用例覆盖 jsdom 无法触达的主进程真实链路（GBK/BOM/大文件 worker 解码、报告写盘、剪贴板、偏好跨实例重启、文件夹真实扫描） · 主进程 dialog stub（showOpenDialog/showSaveDialog 可自动化） · 用例间清空 localStorage 隔离偏好污染 · npm run test:e2e 一键构建+验收，纳入发布 checklist
|
||||
- 文件夹对比（MVP）：新增「对比文件夹」入口（依次选择两侧目录） · 递归扫描按相对路径对齐，文件级状态判定（相同/不同/仅左/仅右；大小不同即不同，大小一致做字节级全量比对，超 10MB 采样头部 8KB 近似判定并标注 ≈） · symlink 跳过防环，单侧文件数上限 10000（超限截断提示） · FolderView 虚拟滚动列表（统计徽章/仅看差异默认开/大小列示） · 双击条目进入单文件对比复用全部 diff 能力，一键返回文件夹列表（扫描结果保留） · file:open 与 file:read-by-path 共用同一读取管线（10MB 上限/编码探测/二进制预警一致）
|
||||
...
|
||||
0.y.z ← 长期停留，永不进入 1.x
|
||||
```
|
||||
@@ -152,9 +155,10 @@ npm run build:win # Windows NSIS 安装包（在 Windows 上）
|
||||
发布前 checklist：
|
||||
1. 更新 `package.json` 的 `version` 到新的 `0.y.z`
|
||||
2. 更新本文件第 3 节演进记录
|
||||
3. 通过质量门禁（typecheck + build）
|
||||
4. 打标签并推送到远程 `git.metona.cn/MetonaTeam/DiffLens`
|
||||
5. 如需发布安装包，生成对应平台产物与 Release 说明
|
||||
3. 通过质量门禁（typecheck + test + build）
|
||||
4. 通过 E2E 验收（`npm run test:e2e`，对 build 产物跑真实 Electron 主链路，0.6.0 起纳入发布必跑）
|
||||
5. 打标签并推送到远程 `git.metona.cn/MetonaTeam/DiffLens`
|
||||
6. 如需发布安装包，生成对应平台产物与 Release 说明
|
||||
|
||||
---
|
||||
|
||||
|
||||
+50
-12
@@ -18,11 +18,11 @@
|
||||
|
||||
| 层级 | 覆盖对象 | 工具 |
|
||||
| --- | --- | --- |
|
||||
| 单元测试（UT） | 纯逻辑：diff 引擎、报告生成器 | Vitest |
|
||||
| 组件测试 | React 组件：应用空态、工具栏交互 | Vitest + Testing Library |
|
||||
| 集成（演进中） | Electron IPC / 多进程协作 | 预留 Playwright 或 Electron 测试 |
|
||||
| 单元测试（UT） | 纯逻辑：diff 引擎、报告生成器、解码探测、文件夹扫描 | Vitest |
|
||||
| 组件测试 | React 组件：应用空态、工具栏交互、文件夹视图 | Vitest + Testing Library |
|
||||
| E2E（0.6.0 起） | 构建产物真实 Electron：主进程解码/写盘/文件夹扫描/偏好重启 | Playwright |
|
||||
|
||||
> 现阶段以**单元 + 组件**为主，覆盖最核心、最易回归的部分。
|
||||
> 单元 + 组件覆盖核心逻辑与交互；E2E 覆盖 jsdom 无法触达的主进程真实链路（mock `window.api` 测不到的部分），发布前必跑。
|
||||
|
||||
---
|
||||
|
||||
@@ -34,7 +34,7 @@
|
||||
| 环境 | jsdom |
|
||||
| React 测试 | @testing-library/react |
|
||||
| 断言扩展 | @testing-library/jest-dom |
|
||||
| 未来 E2E | Playwright（预留，暂不引入） |
|
||||
| E2E | Playwright（`_electron` 模式，复用项目自带 Electron，无需下载浏览器） |
|
||||
|
||||
---
|
||||
|
||||
@@ -42,8 +42,17 @@
|
||||
|
||||
```
|
||||
vitest.config.ts # Vitest 配置（jsdom + 测试范围 + 覆盖率 80% 硬门禁）
|
||||
playwright.config.ts # Playwright E2E 配置（对 out/ 产物启动真实 Electron，发布前必跑）
|
||||
e2e/
|
||||
├── helpers.ts # E2E 辅助（启动应用/对话框 stub/临时 fixture/粘贴入口）
|
||||
└── app.spec.ts # E2E 用例（启动/粘贴/编码链路/选项/导航/导出写盘/文件夹对比/偏好重启）
|
||||
src/main/
|
||||
├── index.ts # 主进程入口（依赖 electron 运行时，覆盖率排除，随发布人工自测）
|
||||
├── index.ts # 主进程入口（依赖 electron 运行时，覆盖率排除，真实链路由 E2E 覆盖）
|
||||
├── decode.ts # 解码与编码探测纯逻辑（Uint8Array 入参，同步与 worker 路径共用）
|
||||
├── decode.test.ts # 解码单元测试（BOM 三种/严格 UTF-8/GBK 回退/二进制启发式）
|
||||
├── decodeWorker.ts # 解码 worker_threads 入口（覆盖率排除，逻辑由 decode 测试覆盖）
|
||||
├── folderScan.ts # 文件夹对比纯逻辑（递归枚举/对齐/字节判定/采样近似）
|
||||
├── folderScan.test.ts # 文件夹扫描单元测试（真实临时目录：状态判定/递归/symlink/截断/近似）
|
||||
├── windowState.ts # 应用状态持久化纯逻辑（bounds 校验/钳制，无 electron 依赖）
|
||||
└── windowState.test.ts # 应用状态单元测试（解析回退/工作区钳制/最小尺寸）
|
||||
src/renderer/src/
|
||||
@@ -63,10 +72,11 @@ src/renderer/src/
|
||||
├── components/
|
||||
│ ├── ContextMenu.test.tsx # 右键菜单（含边缘防溢出）
|
||||
│ ├── DiffView.test.tsx # 对比视图（渲染/滚动同步/右键/拖放）
|
||||
│ ├── FolderView.test.tsx # 文件夹视图（统计/过滤/双击/虚拟滚动/截断与空态提示）
|
||||
│ ├── TextInputModal.test.tsx # 粘贴文本弹窗
|
||||
│ └── Toolbar.test.tsx # 工具栏（选项/导航/导出菜单向上弹出/计算中禁用/字符级开关与空白选项联动灰显勾选+已包含徽标+点击解释+已降级标记）
|
||||
└── __tests__/
|
||||
├── App.test.tsx # 应用集成级测试（加载/拖拽/粘贴/导出/容错/toast 队列/清空确认/状态栏行数/大输入回退）
|
||||
├── App.test.tsx # 应用集成级测试（加载/拖拽/粘贴/导出/容错/toast 队列/清空确认/状态栏行数/大输入回退/文件夹模式进出与双击）
|
||||
└── main.test.ts # 入口挂载冒烟测试
|
||||
```
|
||||
|
||||
@@ -120,6 +130,7 @@ src/renderer/src/
|
||||
- 字符级对比：跨行重组开启后判为完全一致；开启时三个空白选项灰显勾选并带"已包含"徽标，点击弹出解释提示，关闭后恢复用户原勾选状态；内容超限自动降级并 toast 提示（开关旁常显"已降级"标记）；导出报告携带字符级说明；降级后报告按实际生效的行级语义描述选项
|
||||
- 忽略所有空白：仅行内空白不同的两侧文本开启后判为完全一致；导出报告携带比较选项说明
|
||||
- 大输入（超快路径阈值）在无 Worker 环境去抖到期后回退同步计算，完成后无计算中遮罩
|
||||
- 文件夹模式：依次选择两侧目录进入（路径卡片/统计徽章/状态栏切换/默认仅看差异过滤 same） · 任一次选择取消不进入 · 扫描失败 toast 且不进入 · 双击差异条目加载两侧进入单文件对比并可返回文件夹（返回清空两侧面板） · 双击单侧条目加载存在侧并清空另一侧 · 「返回文件对比」清空文件夹状态回单文件空态
|
||||
|
||||
### 5.6 diff 计算 worker 化（`useDiff.ts` / `createDiffWorker.ts`）
|
||||
- 快路径：两侧总行数不超过 2000 时同步计算，不创建 worker，结果与 computeDiff 一致
|
||||
@@ -134,15 +145,42 @@ src/renderer/src/
|
||||
### 5.7 应用状态持久化（`src/main/windowState.ts`）
|
||||
- parseState：空输入/非法 JSON 回退空状态；合法 bounds 与 lastDir 保留；字段类型异常（非矩形/非字符串/空串/非有限数值）防御性忽略
|
||||
- clampBounds：工作区内合法 bounds 原样保留；小于最小尺寸钳到最小值；超出工作区封顶；移出屏幕四向拉回（至少 60px 进入工作区）；多显示器偏移工作区同样钳制；非整数取整；工作区小于最小尺寸时尺寸仍保持最小值
|
||||
- 磁盘读写与窗口事件绑定在主进程入口（覆盖率排除，随发布人工自测）
|
||||
- 磁盘读写与窗口事件绑定在主进程入口（覆盖率排除，真实链路由 E2E 覆盖）
|
||||
|
||||
### 5.8 解码与编码探测（`src/main/decode.ts`）
|
||||
- looksBinary：空输入 / NUL 立即判定 / 纯可见 ASCII / 控制字符占比超 5% / 常见空白不计入
|
||||
- decodeText：UTF-8 BOM（剥离 BOM + 标注）/ UTF-16 LE 与 BE BOM / 仅 BOM 无内容 / 短于 BOM 长度走严格 UTF-8 路径 / 无 BOM 合法 UTF-8 与纯 ASCII / GBK 中文回退解码正确 / 空输入 / 含 NUL 非法 UTF-8 的 GBK 回退 + 二进制判定 / 替换符占比超 5% 判二进制
|
||||
- worker 调度（阈值分流/崩溃回退）在主进程入口（覆盖率排除，大文件 worker 链路由 E2E 覆盖）
|
||||
|
||||
### 5.9 文件夹扫描（`src/main/folderScan.ts`，真实临时目录）
|
||||
- 状态判定：内容一致 same / 同大小内容不同 different / 大小不同 different / 单侧缺失 only（另一侧大小 null）
|
||||
- 递归子目录按相对路径对齐（统一 / 分隔）；二进制内容字节级判定；symlink 跳过；条目字典序排序；total 取两侧较大值
|
||||
- 边界与选项：两个空目录 / 目录不存在抛异常（IPC 层转错误结果） / maxFiles 截断（truncated + total + 条目数受限） / 超 maxContentBytes 同大小文件头部采样一致判 same 带 approximate / 采样头部不同直接 different
|
||||
|
||||
### 5.10 文件夹视图（`FolderView.tsx`）
|
||||
- 渲染：目录路径卡片 / 重新选择与返回按钮 / 统计徽章（相同/不同/仅左/仅右/总数）
|
||||
- 过滤：仅看差异隐藏 same、关闭展示全部；双击回调携带原始条目；大小格式化（B/KB 与缺失占位）；approximate 渲染 ≈ 标注；截断提示；空态提示（无文件 / 全部一致）
|
||||
- 虚拟滚动：大列表仅渲染可见窗口、容器总高度按全部条目撑满
|
||||
|
||||
### 5.11 E2E 端到端（`e2e/app.spec.ts`，对 build 产物启动真实 Electron）
|
||||
- 启动冒烟：标题与双空态面板、空态无导出入口
|
||||
- 粘贴两侧：差异渲染 + 统计徽章（主进程剪贴板链路）
|
||||
- 编码链路：GBK 与 UTF-8 BOM 文件打开（编码标注 + 内容渲染）、大体积 GBK 文件经解码 worker 后台解码完整渲染（状态栏总行数断言）
|
||||
- 比较选项：忽略大小写与忽略所有空白组合、字符级跨行重组判一致
|
||||
- 导航与视图：F7 / Shift+F7、仅看差异折叠、交换左右后面板互换
|
||||
- 报告导出：stub 保存对话框 → 文件真实落盘且含结论与统计
|
||||
- 文件夹对比：真实临时目录扫描（状态判定 / 默认过滤）→ 双击进入单文件对比 → 返回文件夹（扫描结果保留）
|
||||
- 偏好持久化：跨实例重启恢复比较选项与视图开关（同一 userData）
|
||||
- 隔离：每用例启动清空 localStorage + 重载，避免偏好跨用例污染（偏好用例验证实例显式跳过清理）
|
||||
|
||||
---
|
||||
|
||||
## 6. 运行命令
|
||||
|
||||
```bash
|
||||
npm test # 运行全部测试（CI / 提交前）
|
||||
npm test # 运行全部单元 + 组件测试（CI / 提交前）
|
||||
npm run test:watch # 监听模式，开发中用
|
||||
npm run test:e2e # E2E 验收（先 build 再对产物启动真实 Electron；发布前必跑）
|
||||
```
|
||||
|
||||
---
|
||||
@@ -174,9 +212,9 @@ npm run build
|
||||
|
||||
## 9. 演进方向（后续迭代）
|
||||
|
||||
- 接入 Playwright 对打包后的 Electron 应用做端到端验收
|
||||
- 对 IPC 层（open / decode / save-report）补充集成测试
|
||||
- 大文件性能基准测试（虚拟滚动落地后）
|
||||
- 文件夹对比增强（0.7.0 候选）：子目录树形展示 / 按扩展名过滤 / 文件夹对比报告导出 / 语义判定（套用忽略空白等选项）
|
||||
- E2E 覆盖扩展：拖拽导入链路 / 大文件性能基准
|
||||
- 主进程 IPC 层补充集成测试（folder:scan 并发场景）
|
||||
|
||||
---
|
||||
|
||||
|
||||
Reference in New Issue
Block a user