project-test

name: project-test description: 使用此技能维护项目测试文件

Project Test

按这套规则做项目测试：先证明可观察行为，再补实现细节；先加载通用判断，再按任务逐步读取对应技术栈示例。

核心目标

• 让测试回答“功能有没有按要求工作”，而不是“内部是不是刚好这样写”
• 让测试在重构后依然稳，只要行为没变就不该大面积失效
• 让测试一眼能看懂，最好就是 Arrange -> Act -> Assert
• 让边界可控，不碰真实网络，不依赖脏磁盘数据
• 让不同技术栈的测试遵守同一套业务语义

起手流程

flowchart TD
    A["收到测试任务"] --> B["确认被测行为与唯一权威状态"]
    B --> C{"主要技术栈"}
    C -->|Python / pytest| D["读 references/python-pytest.md"]
    C -->|TypeScript / Vitest| E["读 references/typescript-vitest.md"]
    C -->|React / DOM / Hook| F["读 references/react-renderer.md"]
    C -->|跨进程 / 协议 / 事件边界| G["读 references/cross-stack-boundaries.md"]
    B --> H{"是在整改旧测试吗"}
    H -->|是| I["读 references/test-audit.md 与 anti-patterns.md"]
    H -->|否| J["直接写最小有效测试"]
    D --> K["Red -> Green -> Refactor"]
    E --> K
    F --> K
    G --> K
    I --> K
    K --> L["执行对应验证"]

1. 先确认需求、边界、错误分支和状态拥有者。
2. 优先写一个会失败的行为测试，再实现或修正代码。
3. 只加载当前任务需要的参考文件，不把所有示例塞进上下文。
4. 若需要查库或框架 API，使用 $find_docs 查最新官方文档。
5. 验证范围随风险扩大：目标测试 -> 对应测试套件 -> 格式化、lint、类型检查。

硬门闩

1. 每个业务文件有且仅有一个对应测试文件。
2. 与某个业务文件相关的单测、边界用例、回归用例必须收敛到这个对应测试文件中。
3. 公用夹具、测试工具、测试数据 builder 可以独立成文件；它们不能承载某个业务文件的具体断言。
4. 只有跨多个业务文件的真实集成场景，才允许放入独立集成测试文件；文件名必须表达场景边界，而不是复刻某个业务文件名。
5. 新增测试前先查找对应测试文件；找不到时创建一个，不要为同一业务文件新建第二个平行测试文件。
6. 整理旧测试时宁缺毋滥；没有实际业务价值、脱离当前逻辑、理论上可达但实践中基本不可触达的用例，应修改、合并或清理。
7. 允许为提升测试效果做业务透明重构；重构只能改善可测性和边界表达，不得改变业务功能。

通用规则

1. 先走 Red -> Green -> Refactor。
2. 优先断言可观察行为，不把内部实现当主要断言对象。
3. 外部边界才 mock；同仓库内部模块能跑真逻辑就跑真逻辑。
4. 每个测试都要证明一条明确需求、边界或错误分支，并且失败时能说明问题。
5. 测试名直接说业务意图，不写 test_it_works、should handle case 这类空话。
6. 测试数据要有语义，能让读者看出场景。
7. 不为覆盖率数字制造孤儿用例；只补真实需求、边界和历史缺陷。

断言什么

优先断言这些公开结果：

如果一个断言只能说明“内部刚好这么实现”，就先停下来改写测试。

跨栈边界

参考文件路由

文件组织

• Python 测试通常放在集中测试目录，TypeScript/React 测试通常靠近被测模块；以项目现有约定为准。
• 测试文件和业务文件必须一一对应：一个业务文件只对应一个测试文件，一个测试文件也只覆盖一个主业务文件；禁止一对多、多对一、多对多。
• 路径和文件名映射必须可解释、可重复、符合项目约定；发现错位时先统一映射，再迁移或合并用例。
• 对同一业务文件的新增行为、边界、错误分支和回归用例，必须追加到它的对应测试文件中。
• 不要按“成功场景 / 错误场景 / mock 场景”拆出多个平行测试文件。
• 夹具离使用位置越近越好；真正跨域稳定复用的夹具才上提。

旧测试整理流程

改旧测试时，按这个顺序最省事：

1. 读取 references/test-audit.md，先建立业务文件和测试文件的一一映射表。
2. 再读 references/anti-patterns.md，扫 __new__、call_args、call_args_list、tmp_path、mock_open、print\(、vi.mock 套娃、只测实现调用。
3. 逐一说明每个测试真正证明的业务行为；说不清、价值弱或当前业务不会触达的用例，不保留原样。
4. 把“内部调用断言”改成“结果快照断言”，或合并到更有业务价值的场景中。
5. Python 重复准备逻辑收进最近的 conftest.py，前端重复准备逻辑收进同目录 helper 或测试内工厂。
6. 能用真实内存 DB、虚拟文件系统、store 实例或事件流 stub，就不要手造假的系统壳。
7. 跑格式化、静态检查、类型检查和目标测试。

白盒巡检命令

Get-ChildItem -LiteralPath tests -Recurse -File -Filter "*.py" |
  Select-String -Pattern "__new__|call_args|call_args_list|tmp_path|mock_open|print\("

Get-ChildItem -LiteralPath <ts-source-root> -Recurse -File -Include "*.test.ts","*.test.tsx" |
  Select-String -Pattern "toHaveBeenCalled|mock\\.calls|vi\\.mock|console\\."

常用命令

uv run pytest tests/ -v

npm run test

提交前检查

• 测试名能直接说清业务意图
• 测试结构清楚，最好就是 Arrange / Act / Assert
• 测试文件与业务文件保持一一对应，没有为同一业务文件新增第二个平行测试文件
• 已逐一审查用例价值，清理或合并孤儿用例、凑数用例和当前业务基本不会触达的用例
• 没有新增白盒断言、mock 套娃和旧反模式
• 没有不必要的控制台输出，除非输出本身就是被测行为
• 业务透明重构只改善可测性，没有改变对外功能
• Python 夹具放在合适的 conftest.py，前端 helper 没有过早全局化
• 文件系统、数据库、网络、宿主桥接、事件流边界处理符合本规则
• 跑过与改动层级匹配的验证

验证下限