企业官网建设流程全解析

plate 编辑器 Threshold 5 测试覆盖率执行：表格查询、表格变换与纯工具函数的补测实战

【免费下载链接】plateRich-text editor with AI and shadcn/ui项目地址: https://gitcode.com/GitHub_Trending/pl/plate

导读

本文围绕 plate 富文本编辑器仓库中的测试覆盖执行计划 docs/plans/2026-03-23-threshold-5-coverage-execution.md 展开，讲解如何为一轮"覆盖率分数 >= 5 的非 React 文件"批量补齐直接、诚实的测试。文中以表格（table）包的查询与变换、docx-io 的图像尺寸解析、list-classic 的列表兄弟节点移动为具体案例，结合对应源码揭示每个被测函数的实现原理，并给出从定向bun test到 turbo 构建、类型检查、lint 修复的完整验证流水线。读完本文，你将掌握 plate 仓库中"阈值驱动的批量补测"工作流，并理解这些底层工具函数的确切行为契约。

一、背景：什么是 Threshold 5 覆盖执行

plate 仓库的测试治理采用"覆盖率阈值地图（coverage threshold map）"机制，将仓库内大量文件按覆盖分数（coverage score）分档。本文关联的计划文档定义的任务是：

执行刷新后的阈值地图中所有覆盖分数>= 5的当前非 React 文件，且不能演变成又一轮"逐包跳跃（package hop）"式的低效工作。

这一目标的约束条件非常关键：一次专注的、有边界的批量补测，而不是漫无目的地扫遍全仓库。计划明确划定了本轮的执行范围，全部集中在三类"车道（lane）"与两个阈值外的遗留文件上。

从当前仓库状态看，这一计划对应的源码与测试文件已经落地：表格查询与变换目录下均存在同名.spec.tsx文件（如 getTableCellBorders.spec.tsx、deleteRow.spec.tsx），说明该计划的执行产物已在仓库中可查证。

二、执行范围：三条车道与阈值外遗留

2.1 表格查询车道（Table query lane）

覆盖表格的确定性查询（query）函数，均位于 packages/table/src/lib/queries 目录：

2.2 表格变换车道（Table transform lane）

覆盖会修改编辑器文档结构的变换（transform）函数，位于 packages/table/src/lib/transforms：

• deleteRow.ts— 删除当前行，含合并单元格（merge）感知逻辑
• deleteTable.ts— 删除整张表
• deleteColumn.ts— 删除列（要求更深的分支覆盖，因为列删除涉及多个单元格边界分支）
• setTableMarginLeft.ts— 设置表格左边距
• moveSelectionFromCell.ts— 从单元格移动选区
• overrideSelectionFromCell.ts— 覆盖单元格选区

其中overrideSelectionFromCell在 plan 文档写作时还位于 CHANGELOG 中（packages/table/CHANGELOG.md），其能力后来被并入moveSelectionFromCell与shouldMoveSelectionFromCell体系中（仓库中存在 shouldMoveSelectionFromCell.spec.ts），阅读时需留意这一演化。

2.3 表格辅助车道（Table helper lane）

• packages/table/src/lib/merge/deleteRow.ts — 合并感知的行删除核心实现deleteTableMergeRow
• packages/table/src/lib/withSetFragmentDataTable.ts — 表格剪贴板序列化覆盖（CSV / TSV / HTML / Slate fragment）

2.4 表格之外的阈值遗留（Threshold leftovers outside table）

• packages/docx-io/src/lib/internal/utils/image-dimensions.ts — 浏览器兼容的图片尺寸解析器
• packages/list-classic/src/lib/transforms/moveListSiblingsAfterCursor.ts — 移动光标之后的列表兄弟节点

三、测试形态（Test Shape）：契约明确、拒绝冒烟

计划对测试形态给出了四条硬性约束，防止测试退化为无效的"冒烟测试（smoke test）"：

1. 纯辅助函数测试：针对确定性的表格查询与image-dimensions写纯函数测试（不依赖编辑器实例）；
2. 薄编辑器契约测试：针对表格变换与 list-classic 移动写"薄"的编辑器契约测试——只验证对外行为契约，不堆砌实现细节；
3. 无/react：被测目标均为非 React 文件，测试不得引入 React 渲染层；
4. 无浏览器、无宽泛冒烟测试：不依赖浏览器环境，不写覆盖面宽但断言浅的冒烟用例。

这一形态与仓库中查询、变换目录下的.spec.tsx文件相互印证——表格查询的测试文件（如 getTableCellBorders.spec.tsx、getTableEntries.spec.tsx、getTableColumnIndex.spec.tsx）均为轻量契约测试，而非完整渲染冒烟。

四、实现注意事项（Implementation Notes）

计划文档给出了四条贴近实战的实现策略：

• 邻近规约：将表格导航类查询归组进一个相邻的 spec 文件，若这样能让测试夹具（fixtures）更小；
• 复用既有模式：复用已有的表格 hyperscript 与getTestTablePlugins(...)模式，避免每次重复搭建编辑器环境；
• 聚焦分支：优先写聚焦的分支测试（branch tests），而非穷举式表格矩阵（exhaustive table matrices）——这与 2.2 节deleteColumn.ts要求"更深的分支覆盖"形成呼应；
• 暴露真实缺陷时修最小接缝：若某个直接 spec 暴露了真实运行时 bug，修复**最小的接缝（smallest seam）**后继续推进，而不是借机重构大范围代码。

这条"最小接缝修复"原则在实践中意味着：测试先行暴露问题 → 定位到单一函数或单一判断分支 → 只改这一处 → 回到测试继续。

五、源码级剖析：被测函数到底在做什么

5.1 getTableCellBorders：边框合并的边界语义

getTableCellBorders.ts 的实现揭示了表格边框的一个重要语义：

export const getTableCellBorders = (editor, { cellIndices, defaultBorder = { size: 1 }, element }) => { // ... const isFirstCell = col === 0; const isFirstRow = tableNode.children?.[0] === rowNode; return { bottom: getBorder('bottom'), left: isFirstCell ? getBorder('left') : undefined, // 仅首列返回 left right: getBorder('right'), top: isFirstRow ? getBorder('top') : undefined, // 仅首行返回 top }; };

关键行为（源码第 55-74 行）：

• 单元格不是首列时left为undefined，不是首行时top为undefined——这是为了避免内部单元格重复绘制与合并单元格时出现双重边框，是表格边框渲染的"相邻单元格共享边界"策略；
• 默认边框defaultBorder缺省值为{ size: 1 }，各方向取element.borders?.[dir]与默认值的合并结果（color/size/style 逐项兜底）；
• 若单元格不在合法表格内（找不到 row/table 父级或类型不匹配），回退为只返回bottom与right的默认边框。

5.2 deleteRow 与 merge/deleteRow：合并感知的行删除

transforms/deleteRow.ts 是入口，它根据表格配置的disableMerge选项分流：

export const deleteRow = (editor) => { const { getOptions, type } = getEditorPlugin<TableConfig>(editor, { key: KEYS.table }); const { disableMerge } = getOptions(); if (!disableMerge) return deleteTableMergeRow(editor); // 合并模式走 merge/deleteRow // 非合并模式：直接删除行节点，但拒绝删除最后一行 if (currentTableItem[0].children.length > 1) { editor.tf.removeNodes({ at: currentRowItem[1] }); } };

而 merge/deleteRow.ts 中的deleteTableMergeRow是真正复杂的合并感知实现，其核心算法（源码第 48-203 行）：

1. 通过getCellIndices拿到待删单元格的行索引，结合getRowSpan计算删除行区间[deletingRowIndex, endingRowIndex]；
2. 按列优先遍历受影响的单元格（源码注释明确"按列迭代以保持受影响单元格的顺序"），收集affectedCellsSet；
3. 将受影响单元格分流为两类：
   • squizeRowSpanCells：起始行在删除行之上且rowSpan > 1的单元格——需要压缩 rowSpan；
   • moveToNextRowCells：跨越删除区间的单元格——需要下移到下一行并重算 rowSpan；
4. 为需要下移的单元格在下一行中寻找锚点（findIndex比较列索引），通过insertNodes插入新单元格，并同步修正attributes.rowspan；
5. 对需压缩的单元格用setNodes改写 rowSpan；
6. 最后按rowsDeleteNumber次数循环removeNodes删除整行，且当"删除的是唯一一行"（nextRow === undefined && deletingRowIndex === 0）时直接tf.remove.table()删除整张表。

这段代码中if (newCell.attributes?.rowspan)的同步逻辑说明：rowSpan 同时存在于结构字段与attributes属性中，删除行时两者必须保持一致，这正是该类变换测试需要重点断言的契约点。

5.3 withSetFragmentDataTable：剪贴板的多格式序列化

withSetFragmentDataTable.ts 通过OverrideEditor覆盖setFragmentData，将选中的表格区域序列化为四种数据格式（源码第 134-144 行）：

• text/csv：每行用逗号连接单元格纯文本；
• text/tsv：每行用制表符连接（同时作为text/plain的兜底）；
• text/html：重建真实<table>DOM（含th/td、colSpan/rowSpan，并按dangerouslyAllowAttributes白名单透传表格属性）；
• application/x-slate-fragment：对序列化后的表格节点 JSON 做btoa(encodeURIComponent(...))编码，供 Slate 内部粘贴还原。

值得注意的边界分支（源码第 53-62 行）：当用户只选中单个单元格执行 copy/cut 时，直接走原setFragmentData复制单元格内容而非表格结构——这是单格复制与整表复制行为差异的关键分支，也是该文件测试的必测点。整个序列化过程包裹在withoutNormalizing中逐格 select + setFragmentData + 最后恢复initialSelection，属于典型的"读取式变换"，测试中应断言选区最终被还原。

5.4 image-dimensions：无 Node fs 的浏览器兼容解析

image-dimensions.ts 是一个纯函数工具，输入ArrayBuffer | Uint8Array，输出{ width, height, type }。它完全基于**文件魔数（magic bytes）**手写解析，不依赖 Node.js 的fs模块，因此可在浏览器环境运行。支持格式与字节偏移（源码第 21-124 行）：

每个分支都有降级兜底：畸形 JPEG 与无法识别的 WebP 返回{ width: 100, height: 100 }占位，未知格式返回type: 'unknown'。对纯函数测试而言，这正是理想的参数化测试素材：构造各格式的最小字节样本即可验证解析正确性，而不需要真实图片文件。

5.5 moveListSiblingsAfterCursor：列表分割的关键变换

moveListSiblingsAfterCursor.ts 服务于"光标后列表项移出当前列表"的场景（如回车退出嵌套列表、将剩余项转移到新位置）：

export const moveListSiblingsAfterCursor = (editor, { at, to }) => { const offset = at.at(-1)!; at = PathApi.parent(at); // 提升到列表节点 const listNode = NodeApi.get(editor, at)!; if (!match(listNode, [], { type: getListTypes(editor) }) || PathApi.isParent(at, to)) { // 防止在自己列表内部移动 return false; } return editor.tf.moveNodes({ at: listEntry[1], children: true, fromIndex: offset + 1, // 只移动光标之后的兄弟 to, }); };

两个关键契约点（源码第 28-41 行）：

• 目标路径to若位于当前列表内部（PathApi.isParent(at, to)），直接返回false，避免节点在自身列表内自我移动造成死循环或结构错乱；
• 通过fromIndex: offset + 1精确截取"光标之后"的兄弟节点，配合children: true整体迁移子树。

这类变换是典型的"薄编辑器契约测试"对象：只需给定初始文档与at/to路径，断言moveNodes之后列表结构是否符合预期。

六、验证流水线（Verification）：从定向测试到全链路绿

计划文档给出了 8 步验证流程，构成从测试到发布前的完整闭环：

# 1. 对被触碰的 spec 文件跑定向测试 bun test <touched-specs> # 2. 对三个受影响包的目录级测试 bun test packages/table/src packages/docx-io/src/lib/internal/utils packages/list-classic/src/lib/transforms # 3. 性能画像：确认没有引入慢测试（Top 25） pnpm test:profile -- --top 25 packages/table/src packages/docx-io/src packages/list-classic/src # 4. 慢速测试清单（Top 25） pnpm test:slowest -- --top 25 packages/table/src packages/docx-io/src packages/list-classic/src # 5. 依赖安装一致性 pnpm install # 6. 受影响包的构建 pnpm turbo build --filter=./packages/table --filter=./packages/docx-io --filter=./packages/list-classic # 7. 受影响包的类型检查 pnpm turbo typecheck --filter=./packages/table --filter=./packages/docx-io --filter=./packages/list-classic # 8. 全仓库 lint 自动修复 pnpm lint:fix

这套流水线的设计意图值得解读：

• 第 1-2 步验证正确性：先定向（spec 级）后目录级，确保新增测试本身通过，且没有破坏同目录既有测试；
• 第 3-4 步验证性能预算：test:profile与test:slowest都限定 Top 25，对应"快车道预算保持绿色（Fast-lane budget stays green）"的完成标准——新测试不能把慢测试榜单挤爆；
• 第 5 步保证锁文件一致性（bun.lock / pnpm-lock.yaml）；
• 第 6-7 步验证包级构建与类型安全，--filter精确限定受影响包，避免全仓构建的无效耗时；
• 第 8 步统一代码风格（biome/eslint），保证新增测试代码符合仓库规范。

七、完成标准（Done Means）：如何判定本轮收尾

计划文档对"做完"给出了三条明确的验收标准：

1. 每个当前的 threshold-5 文件都有直接、诚实的覆盖——"直接"指测试直击目标函数而非间接命中，"诚实"指断言真实行为而非流于形式；
2. 快车道预算保持绿色——新增测试不得显著拖慢测试套件（与验证第 3-4 步对应）；
3. 剩余未覆盖文件要么低于所选阈值，要么基于价值理由被明确推迟——允许"有理由地不覆盖"，但不允许"无理由地遗漏"。

这三条标准共同定义了批量补测的边界感：覆盖到阈值，但不过度工程；有明确理由的放弃是被允许的。这也解释了为什么计划要求"不演变成逐包跳跃"——补测的粒度是"文件 + 分支"，而不是"包 + 全面扫荡"。

八、小结

Threshold 5 覆盖执行计划展示了 plate 仓库一种可复制的测试治理方法论：

• 以覆盖率阈值地图为筛选器，精准锁定分数>= 5的非 React 文件，避免拍脑袋选文件；
• 以三条车道（查询 / 变换 / 辅助）+ 遗留文件划分范围，同类函数归组处理、复用既有测试模式（hyperscript +getTestTablePlugins）；
• 以"纯函数测试 + 薄契约测试"界定测试形态，拒绝冒烟测试与 React 渲染层的无效开销；
• 以 8 步验证流水线闭环，覆盖正确性、性能预算、依赖一致性、构建、类型与 lint。

对于希望参与 plate 或同类编辑器仓库测试工作的开发者，本文剖析的源码行为（表格边框的共享边界语义、合并行删除的 rowSpan 重整、剪贴板多格式序列化、图片魔数解析、列表兄弟移动的防自移保护）既是测试断言的直接依据，也是理解编辑器底层数据模型与变换契约的绝佳入口。想深入阅读，可从 packages/table/src/lib/queries 与 packages/table/src/lib/transforms 下的.spec.tsx文件入手，对照本文第 5 节逐条验证。

【免费下载链接】plateRich-text editor with AI and shadcn/ui项目地址: https://gitcode.com/GitHub_Trending/pl/plate