project-test

name	project-test
description	新增、修复、审查或整理项目自动化测试，覆盖单元、集成、契约、UI、端到端与回归测试。用于补测试、修复失败或不稳定测试、评估测试质量、清理重复或脆弱测试，以及确定验证范围。

Project Test

用最小、稳定的测试证明请求中的可观察行为。先理解真实调用链和项目约定，再选择足以覆盖风险的测试层级。

工作流程

1. 判断任务模式：审查、诊断、解释或计划只读取和报告；新增、修复或整理才编辑文件。
2. 读取项目事实：适用的 AGENTS.md、项目文档、测试配置、依赖清单、相邻测试和仓库脚本。
3. 先确认存在需要自动化证明的机器行为或契约，并确定精确值是否有独立于实现的权威来源；若改动仅涉及人类阅读内容且没有机器约束，说明无需新增测试并停止。否则定义输入、可观察结果、关键边界或错误分支，以及对应任务模式的完成证据。
4. 按下表选择能观察目标行为的最低测试层级，不因用户提到 UI、API 或数据库就自动升级。
5. 修复缺陷时，能稳定重现就先写失败回归测试；只整理测试或无法可靠制造失败状态时，不强造红测，记录依据并保持行为不变。
6. 实施最小改动，不顺手扩展范围。确需改善可测性时，只做业务透明重构。
7. 按验证门逐级执行目标、受影响范围和仓库级检查，在已有证据足够时停止。
8. 分类验证失败，区分本次引入、既有失败、环境缺口和不稳定失败，不靠反复重跑取得绿色。
9. 报告改动、实际执行的命令、失败项、分类依据和未验证范围。

选择测试层级

仅修改翻译措辞、Agent 指令正文、文档或静态展示文本，不构成自动化测试目标。只有键集合、占位符、格式或模式、解析与加载、运行时选择与回退，或明确要求保持的精确文案等机器契约，才进入测试层级选择。

要证明的行为	最小有效层级
纯规则、转换、校验和错误分支	单元测试
组件、Hook、Context 或局部用户交互	组件或 UI 测试
适配器、存储、文件系统或真实协作者语义	集成测试
API、事件、进程或前后端载荷	生产者与消费者契约测试
浏览器 API、宿主桥接、跨进程启动或完整关键流程	浏览器、端到端或 smoke 测试

仅当真实运行环境本身构成风险时才使用浏览器、端到端或跨进程测试；能由更低层公开结果充分证明时就停在那里。

核心判断

• 断言结果：优先检查返回值、错误、公开状态、事件、持久化结果、DOM 或公开回调；调用次数和参数只在它们本身构成契约时断言。
• 确认字面量权威：精确值只有在协议、格式、迁移、历史兼容、安全边界或明确产品要求提供独立依据时才作为断言。模型规格、视觉参数、静态文案、分页大小、缓存容量和展示数量等可调预设，不逐项复制实现字面量；改测关系、边界和可观察行为。若没有独立行为需要证明，则不新增测试。
• 选择测试替身：优先运行快速、确定且无副作用的真实逻辑。对远程服务、时间、随机数、系统接口、昂贵资源或会干扰测试目的的协作者使用 fake、stub 或 mock；不要只按“仓库内外”机械决定。
• 隔离副作用：除非用户和项目明确提供测试环境，不访问真实用户目录，不向真实外部服务写入，不依赖测试顺序或残留状态。
• 组织文件：遵循仓库现有约定。让同一行为的测试易于发现；按测试层级、场景边界或文件规模拆分确有助于理解时可以拆分，避免重复覆盖同一行为的平行测试。
• 表达业务意图：测试名和数据直接说明需求、边界或历史缺陷；不要为覆盖率数字制造孤儿用例。
• 保持可维护性：夹具和 helper 放在最小共享范围；不暴露私有实现只为方便测试；不通过削弱断言让失败消失。

验证门

1. 目标门：运行最窄目标测试。修复可复现缺陷时，确认它在修复前因预期原因失败、修复后通过。
2. 受影响门：共享 helper、状态、存储、协议或公开入口变化时，运行直接调用者、生产者、消费者或对应测试套件。
3. 仓库门：只在测试基础设施、配置、共享契约或广泛复用代码变化时扩大到全量测试；lint、类型和构建检查使用仓库现有入口，并与改动范围相关。
4. 失败门：疑似不稳定时只为确认重复性做有限重跑并记录频次；既有或环境失败必须有基线、日志或缺失依赖等证据，不得归因猜测。

典型用例

用户请求	关键步骤	完成证据
“修复取消任务后仍显示运行中，并补回归测试”	从公开状态入口稳定复现；先写失败测试；修复共享写入口；运行目标与受影响套件	回归测试修复前按预期失败、修复后通过，相关状态测试通过
“审查这些测试为什么偶发失败”	检查时间、完成信号、共享状态、清理和顺序依赖；只读运行并记录复现频次	每项发现包含位置、复现或静态证据、风险和建议，不修改文件
“API 新增状态字段并更新测试”	确认契约拥有者；分别验证生产者和消费者；仅在序列化本身有风险时增加真实 round-trip	两侧契约测试通过，未覆盖的部署或真实传输风险已说明

完成与停止条件

• 新增或修复：目标行为已有测试证据；修改后的目标测试通过；可复现缺陷保留修复前后的因果证据。
• 审查或诊断：每项结论包含位置、观察证据和实际影响；不把候选信号写成确定缺陷。
• 整理测试：业务行为保持不变；保留、修改、合并、拆分或删除均有风险依据。
• 所有模式：没有未说明的业务变化或无关改动；实际命令、失败分类和未验证范围已经报告。

遇到以下情况时收敛处理：

• 关键业务要求无法从代码、测试或文档推断时，只询问最小阻塞信息。
• 项目命令或依赖不可用时，先寻找仓库内等价入口；不要为了套用示例擅自新增依赖。
• 外部文档确有必要时，优先查阅官方一手资料，并核对项目实际依赖版本。
• 审查旧测试时，不因“看起来不可达”直接删除；先确认公开入口、历史缺陷和风险价值。

参考文件路由

按“技术栈 + 问题类型”组合读取最少必要文件；一个任务可以命中多个维度，不要因此加载全部引用。

技术栈

技术栈	参考文件
Python、pytest、文件系统、数据库、并发	references/python-pytest.md
TypeScript、Vitest、状态或异步逻辑	references/typescript-vitest.md
React、Hook、Context、组件交互	references/react-renderer.md

问题类型

问题类型	参考文件
API、事件、进程、前后端或宿主边界	references/cross-stack-boundaries.md
审查、合并、清理或重构旧测试	references/test-audit.md
定位白盒断言、mock 滥用和测试坏味道	references/anti-patterns.md

例如，审查 React 测试中的 mock 滥用时，组合读取 React、测试审查和反模式引用。若技术栈不在表中，先识别仓库已有框架和命令，再按相同原则工作；不要套用无关示例。