Back to Details

when-to-write-tests

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

When to write tests

何时编写测试

Test observable behavior through the capability's interface. Follow codebase-design for the shared rules and examples. Prefer a few tests that cover real behavior over a test for every private helper.
通过功能的对外接口测试可观测行为。通用规则与示例请遵循codebase-design。与其为每个私有辅助函数都编写测试，不如编写少量覆盖真实行为的测试。

Default

默认情况

No new test.
Smoke the changed path (run the thing). That is verification.
无需新增测试。
对变更路径进行冒烟测试（运行对应功能即可）。这就是验证。

Write a test only when

仅在以下情况编写测试

  • The user asked for one, or
  • A public observable contract is new, changed, or has a reproduced bug that existing tests do not cover (store API, HTTP route, migration backfill, public calculation).
Choose the smallest test that exercises that contract through its interface. For a store, use the real persistence path where practical. For a public pure function, assert its input/output behavior directly. Test failure, ordering, and cleanup when they are part of the contract; do not add a layer of tests for private helpers or assertions about internal calls.
Put it next to the source as 
<file>.test.ts
, not in a separate 
test/
or 
tests/
directory. Only a test that spawns the real server or CLI, or spans packages, goes in the repo-root 
tests/
.
  • 用户明确要求，或
  • 某个公共可观测契约是新增的、发生了变更，或是存在现有测试未覆盖的可复现bug（存储API、HTTP路由、迁移回填、公共计算逻辑）。
选择能通过接口验证该契约的最小范围测试用例。对于存储层逻辑，在可行的情况下使用真实的持久化路径进行测试。对于公共纯函数，直接断言其输入输出行为。如果失败、排序和清理属于契约的一部分，则对其进行测试；不要为私有辅助函数或内部调用的断言额外增加一层测试。
测试文件与源码放在同一目录下，命名为 
<file>.test.ts
，不要放在单独的 
test/
或 
tests/
目录中。只有需要启动真实服务器或CLI、或是跨包的测试，才放在仓库根目录的 
tests/
下。

Do not write a test for

不要为以下情况编写测试

  • Comment / docs-only edits
  • Internal helpers, encoders, or bind-list rewrites already covered by behavior tests
  • "Every new function/method"
  • Edges an advisory invented that are not the contract
  • Refactors that keep the same public behavior (existing tests are the regression net)
  • 仅修改注释/文档的变更
  • 已被行为测试覆盖的内部辅助函数、编码器或绑定列表重写
  • “每个新函数/方法都要测”
  • 由顾问提出的、不属于契约范畴的边界情况
  • 未改变公共行为的重构（现有测试就是回归防护网）

Apply repository requirements

遵循仓库要求

Current user instructions and repository requirements take precedence over this skill. Check existing coverage before adding tests; a required regression test should reproduce the observable bug, not freeze its current implementation. Do not invoke TDD merely because a helper was added or moved. A successful smoke check is useful verification, but does not replace a required automated test.
当前用户指令与仓库要求的优先级高于本技能。新增测试前先检查现有覆盖情况；必要的回归测试应当复现可观测的bug，而非固化当前的实现逻辑。 不要仅仅因为添加或移动了一个辅助函数就采用TDD模式。成功的冒烟检查是有效的验证手段，但不能替代必要的自动化测试。

Fair example

正面示例

Seed old inbound tables, apply the migration, list events, assert facts and metadata survived and the matches table is gone.
填充旧的入站表初始数据，执行迁移，列出事件，断言事实数据与元数据都保留完好，且匹配表已被删除。

Unfair example

反面示例

A test per helper or per comment rewrite. Asserting that 
saveInvoice
called private 
insertRow
rather than that the invoice was saved.
为每个辅助函数或每次注释修改都编写测试。断言 
saveInvoice
调用了私有函数 
insertRow
，而非断言发票已被成功保存。