test-driven-univer-development

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Test-Driven Univer Development

基于测试驱动的Univer开发

Test-Driven Univer Development is package-local project TDD for Univer workbooks. Behavior is complete only when assertion contracts prove the changed packs through

univer sac verify

This is not generic code TDD. The goal is correct Univer package behavior through source, runtime, and assertion evidence. For spreadsheet projects, that includes Excel domain semantics, range roles, formulas, computed values, formatting, validation, protection, preservation, and negative constraints.

<EXTREMELY-IMPORTANT> NO MIGRATION PACK IMPLEMENTATION WITHOUT A PLAN-DERIVED FAILING ASSERTION FIRST.

If you wrote migration source before the assertion failed for the intended workbook-visible reason: Delete or revert the migration source change and restart from the plan-derived assertion gate.

No exceptions:

Do not keep it as reference.
Do not adapt it while writing assertions.
Do not leave it commented out.
Implement fresh from the plan-derived failing assertion.

</EXTREMELY-IMPORTANT>

基于测试驱动的Univer开发是针对Univer工作簿的包级项目测试驱动开发（TDD）。只有当断言合约通过

univer sac verify

验证修改后的包时，行为才视为完整。

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

<EXTREMELY-IMPORTANT> 未先编写基于规划的失败断言，不得实现迁移包。

如果您在断言因预期的工作簿可见原因失败之前就编写了迁移代码：删除或回滚迁移代码变更，从基于规划的断言关口重新开始。

无例外：

不得将其保留为参考。
编写断言时不得对其进行适配。
不得将其注释后保留。
基于规划的失败断言从头实现。

</EXTREMELY-IMPORTANT>

When to Use

适用场景

Use this skill for:

new or changed Facade Migration Packs
```
assertions.ts
```
coverage
```
univer sac apply
```
or
```
univer sac verify
```
repair loops
workbook-visible behavior changes in package-local SaC source
refactoring SaC source while preserving workbook behavior

Exceptions require explicit user agreement and must be recorded in the handoff.

在以下场景中使用此技能：

新建或修改Facade Migration Packs
```
assertions.ts
```
覆盖率提升
```
univer sac apply
```
或
```
univer sac verify
```
修复循环
包级SaC源代码中工作簿可见行为的变更
重构SaC源代码同时保留工作簿行为

例外情况需获得用户明确同意，且必须在交接记录中备案。

Operating Contract

操作约定

Use
```
writing-univer-plans
```
first for complex workbook behavior.
Use
```
executing-univer-plans
```
when following a written plan pack-by-pack.
For complex workbook behavior, assertions trace to the plan, and the plan traces to
```
success-criteria/<topic>.md
```
; do not bypass either source artifact.
Treat
```
assertions.ts
```
as the workbook-visible contract for each non-trivial changed pack.
Allow bounded bootstrap or readonly probes when needed, but never use them as final completion evidence.
Do not claim completion from
```
univer sac apply
```
success.
Do not claim completion from a zero-assertion, all-skipped, or unchecked changed pack verify run.
Do not create empty or no-op Migration Packs just to satisfy pack structure or simulate a RED gate.

针对复杂工作簿行为，先使用
```
writing-univer-plans
```
技能。
遵循书面规划逐个包推进时，使用
```
executing-univer-plans
```
技能。
对于复杂工作簿行为，断言需追溯至规划，而规划需追溯至
```
success-criteria/<topic>.md
```
；不得绕过任一源工件。
将
```
assertions.ts
```
视为每个非平凡修改包的工作簿可见合约。
必要时允许有限的引导或只读探测，但绝不能将其作为最终完成证据。
不得仅因
```
univer sac apply
```
成功就宣称完成。
不得因零断言、全跳过或未检查修改包的验证运行就宣称完成。
不得创建空的或无操作的迁移包，仅为满足包结构或模拟RED关口。

Testing Anti-Patterns Reference

测试反模式参考

Load this reference when writing or changing assertions, creating workbook fixtures, using readonly probes as proof, or tempted to add test-only migration or facade methods:

testing-anti-patterns.md

The reference covers migration echo, readonly probe completion claims, partial workbook fixtures, test-only production surface, rationalizations, and STOP conditions.

编写或修改断言、创建工作簿测试数据、使用只读探测作为证据，或想要添加仅用于测试的迁移或外观方法时，可参考此文档：

testing-anti-patterns.md

。

该参考涵盖迁移回显、只读探测完成宣称、部分工作簿测试数据、仅测试用的生产接口、合理化解释以及STOP条件。

Good Assertions

优质断言

Quality	Good	Bad
Minimal	One workbook behavior decision per assertion	One broad snapshot covering many rules
Clear	Names the sheet, range, and behavior being proved	`assert output is correct`
Domain-grounded	Derives expected values from plan evidence	Copies whatever the migration wrote
Runtime-aware	Checks computed values when formulas matter	Checks formula text only

质量维度	示例	反例
最小化	每个断言验证一项工作簿行为决策	一个宽泛的快照涵盖多条规则
清晰明确	指明要验证的工作表、范围和行为	`assert output is correct`
基于领域	从规划证据推导预期值	直接复制迁移代码的输出内容
感知运行时	当公式重要时检查计算值	仅检查公式文本

Why Order Matters

为何顺序至关重要

Assertions written after migration source are biased by implementation. They answer "what did this migration write?" instead of "what workbook behavior should exist?"

Plan-derived failing assertions force Excel-domain decisions to happen before code. Watching the assertion fail proves the gate catches missing behavior. Passing later proves the Migration Pack satisfied that workbook contract.

Manual preview,

univer sac apply

, and readonly probes are useful evidence, but they are not a repeatable completion gate. The repeatable gate is

univer sac verify <package.univer> --json

plus the corresponding

verify-report.json

在迁移代码之后编写的断言会受实现偏差影响。它们回答的是“此迁移代码输出了什么？”而非“应该存在何种工作簿行为？”。

基于规划的失败断言会促使Excel领域决策在代码编写前确定。观察断言失败可证明关口能捕获缺失的行为。后续断言通过则证明迁移包满足了该工作簿合约。

手动预览、

univer sac apply

和只读探测是有用的证据，但它们并非可重复的完成关口。可重复的关口是

univer sac verify <package.univer> --json

以及对应的

verify-report.json

。

Red-Green-Repair

红-绿-修复流程

dot

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;
}

dot

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 - Write the Assertion First

RED - 先编写断言

Derive assertions from the plan: user intent, baseline evidence, range roles, final-layout reasoning, and Contract Decision Evidence.

Do not derive assertions from whatever the migration happened to write.

Assertions should cover:

workbook-visible final state: sheets, used ranges, headers, representative values, formulas, and computed values
Excel domain semantics: signs, categories, period boundaries, text casing, blank-versus-zero, blank-versus-error placeholders, singular/plural label preservation, stored value type, display-critical values, and formula behavior
range role preservation: source data, helper/control input, lookup/reference, example/demo, existing output, and preserve-only ranges
boundary and negative constraints: no extra headings, no helper sheets, cleared tails, no unintended overwrite, no unwanted formatting changes
style/export safety: valid
```
#RRGGBB
```
or documented color strings, expected number formats, and export-compatible workbook-visible values when styles or formulas are involved
workbook-behavior contract decisions: output shape, sorting, grouping, mapping, value/formula semantics, formatting/presentation, interaction/validation/protection, preservation, and negative constraints
meaningful cases: first, middle, last, blank, zero, date-boundary, text-boundary, and grouping-boundary rows when relevant

Keep assertions small and deterministic. Prefer representative ranges over broad workbook snapshots.

从规划推导断言：用户意图、基准证据、范围角色、最终布局推理以及合约决策证据。

不得从迁移代码的实际输出推导断言。

断言应涵盖：

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

保持断言小巧且确定。优先选择代表性范围，而非宽泛的工作簿快照。

Verify RED - Watch It Fail

验证RED - 观察断言失败

univer sac verify <package.univer> --json

verifies applied packs. It does not apply pending source just to test assertions. For a brand-new pending pack, the RED gate is established by writing the plan-derived assertion before implementation and confirming that the missing behavior is still absent from workbook-visible baseline evidence.

Only run verify for RED when the target pack is already applied or when you are repairing an applied pack and expect its assertion to fail. When you run verify, confirm:

the changed pack is actually checked in the JSON summary or
```
verify-report.json
```
the assertion fails
the failure is about the intended workbook-visible behavior
the failure is not a typo, missing fixture, setup error, stale apply state, skipped pack, or invalid assertion

These are not valid RED gates:

```
SAC_EMPTY_MIGRATION_PACK
```
```
SAC_PACK_FILE_INVALID
```
```
checkedPacks: 0
```
,
```
checkedPackCount: 0
```
, or an all-skipped run
a no-op sheet migration whose pack is skipped because it has not been applied
a verify pass that does not check the changed pack's assertions

If verify cannot check the changed pack yet, do not add an empty/no-op pack just to make verify run. The next GREEN step may create the minimal real migration source only after the assertion file exists and baseline evidence confirms the behavior is missing.

If an assertion passes immediately for a changed pack that verify actually checked, it is not a useful gate for new behavior. Strengthen it or choose the next missing behavior from the plan.

univer sac verify <package.univer> --json

用于验证已应用的包。它不会为了测试断言而应用未提交的源代码。对于全新的待提交包，RED关口的建立方式是：先编写基于规划的断言，再确认工作簿可见的基准证据中仍缺失该行为。

仅当目标包已应用，或您正在修复已应用的包且预期其断言会失败时，才运行RED验证。运行验证时需确认：

修改后的包确实在JSON摘要或
```
verify-report.json
```
中被检查
断言失败
失败原因与预期的工作簿可见行为相关
失败并非由拼写错误、缺失测试数据、设置错误、过期应用状态、跳过的包或无效断言导致

以下情况不属于有效的RED关口：

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

如果验证暂时无法检查修改后的包，请勿添加空的/无操作的包来让验证运行。下一步GREEN操作可能仅在断言文件存在且基准证据确认行为缺失后，才创建最小化的真实迁移代码。

如果验证实际检查了修改后的包，但断言立即通过，则它对于新行为而言并非有用的关口。需强化该断言，或从规划中选择下一个缺失的行为。

GREEN - Implement the Minimal Pack Change

GREEN - 实现最小化包变更

Edit the Migration Pack only after the applicable RED gate exists: for an already-applied pack, the assertion fails for the intended reason; for a brand-new pending pack, the plan-derived assertion exists and baseline evidence confirms the behavior is missing.

Implement only what the current pack and assertion require. Do not add unrelated sheets, helper ranges, broad formatting, or future behavior.

仅在适用的RED关口存在后，才编辑迁移包：对于已应用的包，断言因预期原因失败；对于全新的待提交包，基于规划的断言已存在且基准证据确认行为缺失。

仅实现当前包和断言所需的内容。请勿添加无关的工作表、辅助范围、宽泛的格式设置或未来行为。

Verify GREEN - Use the Report

验证GREEN - 使用报告

Run apply when the relevant migration is not yet applied, then verify:

bash

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

Read the JSON summary and

internal/sac/runs/<run-id>/verify-report.json

Confirm that the changed pack is checked and has at least one passed assertion. A zero-assertion, all-skipped, or unchecked changed-pack run is not GREEN.

If status is

failed

, inspect pack id, assertion kind, target, expected value, actual value, and first difference when present. Decide whether the migration source or assertion expectation is wrong before changing either.

If status is

error

, fix setup, config, missing target, source validation, bundling, or runtime setup before judging workbook behavior.

If a pack has already been applied and later needs behavior changes, do not keep editing that applied pack into a hash mismatch loop. Prefer a new follow-up Migration Pack that repairs the behavior and has its own assertions.

当相关迁移尚未应用时，先运行apply再验证：

bash

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

查看JSON摘要和

internal/sac/runs/<run-id>/verify-report.json

。

确认修改后的包已被检查，且至少有一个通过的断言。零断言、全跳过或未检查修改包的运行不属于GREEN状态。

如果状态为

failed

，检查包ID、断言类型、目标、预期值、实际值以及存在的第一个差异。在修改迁移代码或断言预期之前，先判断哪一方有误。

如果状态为

error

，先修复设置、配置、缺失目标、源代码验证、打包或运行时设置，再评估工作簿行为。

如果某个包已应用，之后需要变更行为，请勿持续编辑该已应用包导致哈希不匹配循环。优先选择新建一个后续迁移包来修复行为，并为其添加单独的断言。

REPAIR - Keep the Contract Honest

REPAIR - 保持合约可信

Readonly probes such as inspect, pipe out, or readonly runtime commands may help debug failures. Convert useful probe findings back into the plan, migration source, or assertions, then return to

univer sac verify

If verification changes expected behavior, update the plan before or alongside source/assertion repairs.

只读探测（如检查、导出或只读运行时命令）可帮助调试失败。将有用的探测结果整合回规划、迁移代码或断言中，然后回到

univer sac verify

。

如果验证变更了预期行为，在修复源代码/断言之前或同时更新规划。

Assertion Coverage Rules

断言覆盖规则

For each high-risk decision recorded in the plan's Contract Decision Evidence table, add at least one assertion or readonly probe that distinguishes the chosen rule from a plausible wrong rule.

Examples:

sort/group/truncation decisions: verify first, middle, last, and the first excluded candidate when output capacity is limited
mapping decisions: verify representative source-to-target coordinates, including one row for each side of a category, sign, blank/zero, or boundary mapping when relevant
text decisions: verify exact casing, whitespace, abbreviations, singular/plural wording, and stored value type
structural decisions: verify section headers, segment boundaries, and first/last row after the final layout is determined
blank/error decisions: verify at least one no-match or missing-data row that would distinguish a real blank from
```
#N/A
```
,
```
n/a
```
, spaces, NBSP, or zero
date-window decisions: verify the first computed row, the row before and after the boundary, one middle row, and the last row
stale/example target decisions: when existing target values could be stale examples or partial output, verify at least one counterexample that would fail if those values were incorrectly preserved
style decisions: verify normalized color strings and exported workbook compatibility when an invalid or ambiguous color token appears in the request

A passed assertion that only mirrors the migration output is not enough when the underlying semantic decision was ambiguous. If the same assertion would pass for the plausible wrong rule, strengthen it or add a readonly probe before treating the pack as GREEN.

Do not treat a passing assertion as GREEN if it only confirms copied existing target values without proving they match the instruction-derived workbook behavior.

For exact-value decisions, assertions should prove the workbook-visible contract rather than the implementation's preferred normalization. Cover exact casing, whitespace, punctuation, identifiers, stored value type, dates, booleans, blanks, zeroes, and error placeholders when those details are visible or were part of a high-risk decision.

Assertions cannot turn an underdetermined assumption into workbook-proven truth. When the plan marks a decision as

underdetermined assumption

, assertions should verify that the implementation consistently applies the declared assumption, and the final handoff should preserve that uncertainty instead of presenting it as decisive workbook evidence.

对于规划的合约决策证据表中记录的每个高风险决策，添加至少一个断言或只读探测，以区分所选规则与合理的错误规则。

示例：

排序/分组/截断决策：验证首行、中间行、末行，以及输出容量有限时第一个被排除的候选行
映射决策：验证代表性的源到目标坐标，包括分类、符号、空白/零或边界映射相关的每一侧至少一行
文本决策：验证精确的大小写、空格、缩写、单复数措辞以及存储值类型
结构决策：验证章节标题、分段边界，以及最终布局确定后的首行/末行
空白/错误决策：验证至少一行无匹配或缺失数据的行，以区分真实空白与
```
#N/A
```
、
```
n/a
```
、空格、NBSP或零
日期窗口决策：验证第一个计算行、边界前后的行、一个中间行以及末行
过期/示例目标决策：当现有目标值可能是过期示例或部分输出时，验证至少一个反例，若错误保留这些值则该反例会失败
样式决策：当请求中出现无效或模糊的颜色标记时，验证标准化的颜色字符串和导出的工作簿兼容性

当底层语义决策存在歧义时，仅通过镜像迁移输出的断言是不够的。如果同一断言对合理的错误规则也会通过，则需强化该断言或添加只读探测，再将包视为GREEN状态。

如果断言仅确认复制的现有目标值，而未证明它们符合基于指令的工作簿行为，则不得将其视为GREEN状态。

对于精确值决策，断言应证明工作簿可见合约，而非实现偏好的标准化。当这些细节可见或属于高风险决策时，需覆盖精确的大小写、空格、标点、标识符、存储值类型、日期、布尔值、空白、零值和错误占位符。

断言无法将未确定的假设转化为工作簿已验证的事实。当规划将某决策标记为

underdetermined assumption

时，断言应验证实现是否一致应用了声明的假设，且最终交接需保留该不确定性，而非将其作为决定性的工作簿证据。

Passing Gate

通过关口

For non-trivial SaC TDD handoff:

the latest relevant

univer sac verify <package.univer> --json

status must be

passed

every pack created or modified for the task must be checked unless explicitly assertion-free
each changed pack must have at least one passed assertion
skipped packs must be mentioned when relevant
zero-assertion and all-skipped runs are not completion signals

对于非平凡的SaC TDD交接：

Final Handoff

最终交接

When an external harness supplies a delivery or stop gate, follow that harness after the latest relevant verify passes. Do not keep collecting auxiliary evidence after the required handoff artifact is created.

The final handoff must include:

plan outcome and pack sequence
verification command
final status
```
verify-report.json
```
path
changed pack assertion evidence
skipped packs, if relevant
auxiliary probes used, if any, and why they were not completion evidence

当外部流程提供交付或停止关口时，在最新的相关验证通过后遵循该流程。创建所需的交接工件后，请勿继续收集辅助证据。

最终交接必须包含：

规划结果和包序列
验证命令
最终状态
```
verify-report.json
```
路径
修改包的断言证据
相关的跳过包（如有）
使用的辅助探测（如有），以及为何未将其作为完成证据