| name | project-test |
| description | 新增、修复、审查或整理项目自动化测试，覆盖单元、集成、契约、UI、端到端与回归测试。用于补测试、修复失败或不稳定测试、评估测试质量、清理重复或脆弱测试，以及确定验证范围。 |
Project Test
用最小、稳定的测试证明请求中的可观察行为。先理解真实调用链和项目约定，再选择足以覆盖风险的测试层级。
工作流程
- 判断任务模式：审查、诊断、解释或计划只读取和报告；新增、修复或整理才编辑文件。
- 读取项目事实：适用的
AGENTS.md、项目文档、测试配置、依赖清单、相邻测试和仓库脚本。
- 先确认存在需要自动化证明的机器行为或契约，并确定精确值是否有独立于实现的权威来源；若改动仅涉及人类阅读内容且没有机器约束，说明无需新增测试并停止。否则定义输入、可观察结果、关键边界或错误分支，以及对应任务模式的完成证据。
- 按下表选择能观察目标行为的最低测试层级，不因用户提到 UI、API 或数据库就自动升级。
- 修复缺陷时，能稳定重现就先写失败回归测试；只整理测试或无法可靠制造失败状态时，不强造红测，记录依据并保持行为不变。
- 实施最小改动，不顺手扩展范围。确需改善可测性时，只做业务透明重构。
- 按验证门逐级执行目标、受影响范围和仓库级检查，在已有证据足够时停止。
- 分类验证失败，区分本次引入、既有失败、环境缺口和不稳定失败，不靠反复重跑取得绿色。
- 报告改动、实际执行的命令、失败项、分类依据和未验证范围。
选择测试层级
仅修改翻译措辞、Agent 指令正文、文档或静态展示文本，不构成自动化测试目标。只有键集合、占位符、格式或模式、解析与加载、运行时选择与回退，或明确要求保持的精确文案等机器契约，才进入测试层级选择。
| 要证明的行为 | 最小有效层级 |
|---|
| 纯规则、转换、校验和错误分支 | 单元测试 |
| 组件、Hook、Context 或局部用户交互 | 组件或 UI 测试 |
| 适配器、存储、文件系统或真实协作者语义 | 集成测试 |
| API、事件、进程或前后端载荷 | 生产者与消费者契约测试 |
| 浏览器 API、宿主桥接、跨进程启动或完整关键流程 | 浏览器、端到端或 smoke 测试 |
仅当真实运行环境本身构成风险时才使用浏览器、端到端或跨进程测试；能由更低层公开结果充分证明时就停在那里。
核心判断
- 断言结果：优先检查返回值、错误、公开状态、事件、持久化结果、DOM 或公开回调；调用次数和参数只在它们本身构成契约时断言。
- 确认字面量权威：精确值只有在协议、格式、迁移、历史兼容、安全边界或明确产品要求提供独立依据时才作为断言。模型规格、视觉参数、静态文案、分页大小、缓存容量和展示数量等可调预设，不逐项复制实现字面量；改测关系、边界和可观察行为。若没有独立行为需要证明，则不新增测试。
- 选择测试替身：优先运行快速、确定且无副作用的真实逻辑。对远程服务、时间、随机数、系统接口、昂贵资源或会干扰测试目的的协作者使用 fake、stub 或 mock；不要只按“仓库内外”机械决定。
- 隔离副作用：除非用户和项目明确提供测试环境，不访问真实用户目录，不向真实外部服务写入，不依赖测试顺序或残留状态。
- 组织文件：遵循仓库现有约定。让同一行为的测试易于发现；按测试层级、场景边界或文件规模拆分确有助于理解时可以拆分，避免重复覆盖同一行为的平行测试。
- 表达业务意图：测试名和数据直接说明需求、边界或历史缺陷；不要为覆盖率数字制造孤儿用例。
- 保持可维护性：夹具和 helper 放在最小共享范围；不暴露私有实现只为方便测试；不通过削弱断言让失败消失。
验证门
- 目标门：运行最窄目标测试。修复可复现缺陷时，确认它在修复前因预期原因失败、修复后通过。
- 受影响门：共享 helper、状态、存储、协议或公开入口变化时，运行直接调用者、生产者、消费者或对应测试套件。
- 仓库门：只在测试基础设施、配置、共享契约或广泛复用代码变化时扩大到全量测试；lint、类型和构建检查使用仓库现有入口，并与改动范围相关。
- 失败门：疑似不稳定时只为确认重复性做有限重跑并记录频次；既有或环境失败必须有基线、日志或缺失依赖等证据，不得归因猜测。
典型用例
| 用户请求 | 关键步骤 | 完成证据 |
|---|
| “修复取消任务后仍显示运行中，并补回归测试” | 从公开状态入口稳定复现；先写失败测试；修复共享写入口；运行目标与受影响套件 | 回归测试修复前按预期失败、修复后通过，相关状态测试通过 |
| “审查这些测试为什么偶发失败” | 检查时间、完成信号、共享状态、清理和顺序依赖；只读运行并记录复现频次 | 每项发现包含位置、复现或静态证据、风险和建议，不修改文件 |
| “API 新增状态字段并更新测试” | 确认契约拥有者；分别验证生产者和消费者；仅在序列化本身有风险时增加真实 round-trip | 两侧契约测试通过，未覆盖的部署或真实传输风险已说明 |
完成与停止条件
- 新增或修复：目标行为已有测试证据；修改后的目标测试通过；可复现缺陷保留修复前后的因果证据。
- 审查或诊断：每项结论包含位置、观察证据和实际影响；不把候选信号写成确定缺陷。
- 整理测试：业务行为保持不变；保留、修改、合并、拆分或删除均有风险依据。
- 所有模式：没有未说明的业务变化或无关改动；实际命令、失败分类和未验证范围已经报告。
遇到以下情况时收敛处理：
- 关键业务要求无法从代码、测试或文档推断时，只询问最小阻塞信息。
- 项目命令或依赖不可用时，先寻找仓库内等价入口；不要为了套用示例擅自新增依赖。
- 外部文档确有必要时，优先查阅官方一手资料，并核对项目实际依赖版本。
- 审查旧测试时，不因“看起来不可达”直接删除；先确认公开入口、历史缺陷和风险价值。
参考文件路由
按“技术栈 + 问题类型”组合读取最少必要文件；一个任务可以命中多个维度，不要因此加载全部引用。
技术栈
问题类型
例如，审查 React 测试中的 mock 滥用时，组合读取 React、测试审查和反模式引用。若技术栈不在表中，先识别仓库已有框架和命令，再按相同原则工作；不要套用无关示例。
