test-driven-univer-development

测试驱动的 Univer 开发

测试驱动的 Univer 开发是针对 Univer 工作簿的包内 SaC TDD。只有当断言契约通过 univer sac verify 证明变更包的行为正确时，工作才算完成。

这不是通用的代码 TDD。目标是通过源码、运行时和断言证据，确保 Univer 包的行为正确。对于电子表格项目，这包括 Excel 领域语义、区域角色、公式、计算值、格式、验证、保护、保留规则和负向约束。

未先通过基于计划的断言得到失败结果，不得实现迁移包。

如果你在断言因预期的工作簿可见原因失败之前就编写了迁移源码：删除或还原迁移源码变更，然后从基于计划的断言门禁重新开始。

没有例外：

• 不得将其留作参考。
• 编写断言时不得调整它。
• 不得将其注释后留在代码中。
• 必须从基于计划的失败断言开始，重新实现。

适用场景

在以下情况下使用此技能：

• 新建或变更 Facade Migration Pack
• 编写 assertions.ts 覆盖
• 使用 univer sac apply 或 univer sac verify 进行修复循环
• 在包内 SaC 源码中变更工作簿可见行为
• 重构 SaC 源码，同时保留工作簿行为

例外情况需要获得用户明确同意，并记录在交接文档中。

操作约定

• 对复杂的工作簿行为，先使用 writing-univer-plans。
• 按照书面计划逐包执行时，使用 executing-univer-plans。
• 对于复杂的工作簿行为，断言必须追溯到计划，计划必须追溯到 success-criteria/<topic>.md；不得绕过任一来源文档。
• 将 assertions.ts 视为每个发生非平凡变更的包的工作簿可见行为契约。
• 必要时可进行范围受限的引导探查或只读探查，但绝不能将其作为最终完成证据。
• 不得仅凭 univer sac apply 成功就宣称完成。
• 不得仅凭断言数为零、全部跳过或未经检查的变更包验证运行就宣称完成。
• 不得创建空的或无操作的 Migration Pack 来满足包结构要求或模拟 RED 门禁。

测试反模式参考

在编写或修改断言、创建工作簿固定样例、将只读探查用作证明，或打算添加仅用于测试的迁移方法或 facade 方法时，请加载此参考： testing-anti-patterns.md。

该参考涵盖迁移回显、只读探查完成声明、不完整的工作簿固定样例、仅供测试使用的生产接口、合理化借口和 STOP 条件。

优质断言

质量	优质	不佳
精简	每个断言只验证一个工作簿行为决策	一个宽泛的快照涵盖许多规则
清晰	明确指出要验证的工作表、区域和行为	assert output is correct
基于领域	根据计划证据推导预期值	照抄迁移写入的内容
考虑运行时	公式相关时检查计算值	只检查公式文本

顺序为何重要

在迁移源码编写完成后再写断言，会导致断言受到实现方式的影响。它们回答的是“此迁移写入了什么？”，而不是“工作簿应具备什么行为？”

基于计划的失败断言会迫使你在编写代码之前先作出 Excel 领域决策。观察断言失败，可以证明门禁能够捕获缺失的行为。之后断言通过，则证明 Migration Pack 满足了工作簿契约。

手动预览、univer sac apply 和只读探查都是有用的证据，但不能作为可重复的完成门禁。可重复的门禁是 univer sac verify <package.univer> --json 及其返回的断言证据。

红—绿—修复

digraph test_driven_univer_development {
    rankdir=LR;
    red [label="RED\nPlan-derived assertion", shape=box, style=filled, fillcolor="#ffcccc"];
    verify_red [label="Verify fails\nfor right workbook reason", shape=diamond];
    green [label="GREEN\nMinimal Migration Pack", shape=box, style=filled, fillcolor="#ccffcc"];
    verify_green [label="Verify passes\nwith report evidence", shape=diamond];
    repair [label="REPAIR\nSource, assertion, or plan", shape=box, style=filled, fillcolor="#ccccff"];
    next [label="Next pack", shape=ellipse];

    red -> verify_red;
    verify_red -> green [label="yes"];
    verify_red -> red [label="wrong failure"];
    green -> verify_green;
    verify_green -> repair [label="yes"];
    verify_green -> green [label="no"];
    repair -> verify_green [label="stay green"];
    verify_green -> next;
}

RED - 先编写断言

根据计划推导断言：用户意图、基线证据、区域角色、最终布局推理以及 Contract Decision Evidence。

不要根据迁移实际写入的内容推导断言。

断言应涵盖：

• 工作簿中可见的最终状态：工作表、已用区域、表头、有代表性的值、公式和计算值
• Excel 领域语义：正负号、类别、周期边界、文本大小写、空白与零的区别、空白与错误占位符的区别、单复数标签保留、存储值类型、显示关键值以及公式行为
• 区域角色保留：源数据、辅助/控制输入、查找/参考、示例/演示、现有输出和仅保留区域
• 边界与负向约束：无多余标题、无辅助工作表、尾部已清除、无意外覆盖、无不需要的格式更改
• 样式/导出安全性：有效的 #RRGGBB 或有文档说明的颜色字符串、预期数字格式，以及涉及样式或公式时与导出兼容的工作簿可见值
• 工作簿行为契约决策：输出形状、排序、分组、映射、值/公式语义、格式/呈现、交互/验证/保护、保留和负向约束
• 有意义的用例：相关时涵盖首行、中间行、末行、空白、零、日期边界、文本边界和分组边界行

保持断言精简且确定。优先选择有代表性的区域，而非对整个工作簿做宽泛快照。

验证 RED - 确认其失败

univer sac verify <package.univer> --json 用于验证已应用的包。它不会仅为了测试断言而应用待处理的源代码。对于全新的待处理包，RED 门槛的建立方式是：在实现前编写由计划推导的断言，并确认基线证据中仍缺少该行为。

只有在目标包已应用，或正在修复一个已应用的包且预期其断言会失败时，才运行 RED 验证。运行验证时，请确认：

• JSON 摘要中确实检查了已更改的包
• 断言失败
• 失败针对的是预期的工作簿可见行为
• 失败不是由拼写错误、缺少测试夹具、设置错误、过期的应用状态、跳过的包或无效断言造成的

以下情况不能作为有效的 RED 门槛：

• SAC_EMPTY_MIGRATION_PACK
• SAC_PACK_FILE_INVALID
• checkedPacks: 0、checkedPackCount: 0 或全部跳过的运行
• 因尚未应用而被跳过的无操作工作表迁移包
• 未检查已更改包断言的验证通过结果

如果验证尚无法检查已更改的包，不要仅为了让验证运行而添加空包/无操作包。只有在断言文件已存在且基线证据确认缺少该行为后，下一步 GREEN 才可以创建最精简的真实迁移源代码。

如果验证实际检查了已更改的包，而断言立即通过，那么它就不是针对新行为的有效门槛。请强化断言，或从计划中选择下一个缺失的行为。

GREEN - 实施最小包更改

只有在相应的 RED 门槛已建立后，才编辑 Migration Pack：对于已应用的包，断言因预期原因而失败；对于全新的待处理包，已存在由计划推导的断言，且基线证据确认缺少该行为。

只实现当前包和断言所要求的内容。不要添加无关工作表、辅助区域、宽泛格式或未来行为。

验证 GREEN - 使用报告

如果尚未应用相关迁移，请运行 apply，然后进行验证：

univer sac apply <package.univer>
univer sac verify <package.univer> --json

阅读 JSON 摘要和返回的断言证据。

确认已检查更改过的 pack，且至少有一项断言通过。断言数为零、全部跳过，或未检查更改过的 pack，都不算 GREEN。

如果状态为 failed，请检查 pack id、断言类型、目标、预期值、实际值，以及（如有）首个差异。在更改迁移源或断言预期值之前，先判断哪一方有误。

如果状态为 error，请先修复设置、配置、缺失的目标、源验证、打包或运行时设置，再判断工作簿行为。

如果某个 pack 已应用，之后又需要更改行为，请勿继续编辑该已应用的 pack，导致哈希不匹配循环。建议新建一个后续 Migration Pack 来修复行为，并为其添加自己的断言。

修复 - 保持契约真实

只读探查（如 inspect、pipe out 或只读运行时命令）可能有助于调试失败。将有用的探查结果转化为计划、迁移源或断言，然后返回 univer sac verify。

如果验证改变了预期行为，请在修复源或断言之前或同时更新计划。

断言覆盖规则

对于计划的 Contract Decision Evidence 表中记录的每个高风险决策，至少添加一项断言或只读探查，以区分选定规则与一种合理的错误规则。

例如：

• 排序／分组／截断决策：验证首个、中间、最后一个候选项，以及输出容量受限时首个被排除的候选项
• 映射决策：验证有代表性的源坐标到目标坐标的映射；在相关情况下，每个类别、正负、空白／零值或边界映射的两侧至少验证一行
• 文本决策：验证大小写、空格、缩写、单复数措辞以及存储值类型是否完全一致
• 结构决策：在最终布局确定后，验证分节标题、分段边界以及首行／末行
• 空白／错误值决策：验证至少一行无匹配项或缺失数据，以区分真正的空白与 #N/A、n/a、空格、NBSP 或零值
• 日期窗口决策：验证首个计算行、边界前后各一行、中间一行以及最后一行
• 陈旧／示例目标决策：如果现有目标值可能是陈旧示例或部分输出，请至少验证一个反例；若错误地保留这些值，该反例应会失败
• 样式决策：当请求中出现无效或含义不明确的颜色标记时，验证规范化后的颜色字符串以及导出工作簿的兼容性

当底层语义决策存在歧义时，仅仅复现迁移输出的断言并不足够。如果合理的错误规则也能通过同一断言，请增强断言或添加只读探查，然后再将 pack 视为 GREEN。

如果一项通过的断言只是确认了复制的现有目标值，却没有证明这些值符合指令所要求的工作簿行为，请勿将其视为 GREEN。

对于精确值决策，断言应证明工作簿中可见的契约，而不是实现所偏好的规范化结果。对于可见的细节或高风险决策涉及的细节，应覆盖大小写、空格、标点、标识符、存储值类型、日期、布尔值、空白、零值和错误占位符是否完全一致。

断言无法将未充分确定的假设变成经工作簿证明的事实。如果计划将某项决策标记为 underdetermined assumption，断言应验证实现是否一致地采用了所声明的假设；最终交接时也应保留这种不确定性，而不是将其表述为决定性的工作簿证据。

通过门槛

对于非平凡的 SaC TDD 交接：

• 最新的相关 univer sac verify <package.univer> --json 状态必须为 passed
• 必须检查为该任务创建或修改的每个 pack，除非明确声明其不含断言
• 每个已更改的 pack 至少必须有一条通过的断言
• 相关时必须提及已跳过的 pack
• 零断言和全部跳过的运行都不能作为完成信号

最终交接

当外部 harness 提供交付或停止门槛时，在最新的相关 verify 通过后，遵循该 harness。创建所需的交接产物后，不要继续收集辅助证据。

最终交接必须包括：

• 计划执行结果和 pack 顺序
• 验证命令
• 最终状态
• 已更改 pack 的断言证据
• 已跳过的 pack（如相关）
• 使用过的辅助探测（如有），以及它们为何不构成完成证据