build-scenario-tests

构建场景测试

将一份简短的行为约定编译为确定性、符合代码库惯例的测试代码。在选择测试框架、命令、测试夹具、选择器或断言之前，先了解宿主项目。

操作约定

• 以代码库说明和现有测试为准。
• 每个场景只聚焦一种行为和一种失败原因。
• 使用代码库已有的测试栈进行编译。只有在没有合适的测试框架且用户接受取舍时，才添加依赖。
• 确保设置、输入、操作和预期结果都是确定性的。
• 优先验证公开行为，而非实现细节。断言用户或外部调用方可观察到的内容。
• 将 Markdown 场景放在测试旁边，或放在代码库既定的规范目录中。在两个产物中都记录对应关系。
• 切勿仅为了让测试通过而弱化断言。

工作流

1. 通过代码库理解关卡

阅读最近的 AGENTS.md 或同等说明、产品 README、贡献指南、清单、测试配置，以及最相关且范围最小的产品文档。使用代码库搜索查找实现入口、相邻测试、测试夹具、稳定选择器和验证命令。沿着相关操作，从公开入口追踪到状态边界，再到可观察结果。没有理由时，不要阅读整个目录树。

编辑前，确保能够说明：

product surface:
behavior source:
relevant architecture and data flow:
runtime or start command:
existing test runner:
nearest tests to imitate:
fixture and state-isolation strategy:
narrow validation command:
full validation command:
known trust or destructive boundaries:

如果有重要字段未知，请再次搜索。如果代码库中没有答案，请指出缺口，并且只询问缺失的产品决策。不要臆造命令、选择器、凭据或预期行为。

2. 规范化场景

阅读 references/scenario-format.md。如果用户提供了散文描述，请将其改写为符合该约定的场景，不要改变原意。

遇到以下情况时，拒绝或拆分场景：

• 包含多个彼此独立的行为；
• 依赖主观的视觉判断；
• 需要不受控的第三方状态、真实支付或人工授权；
• 使用“运行正常”等模糊结果；
• 无法重置数据、时间、随机性或网络依赖。

将宽泛的流程或需要 Agent 判断的流程转交给冒烟测试工作流。

3. 将意图映射到宿主测试栈

编写代码前，先创建一份简洁的映射：

场景元素	代码库实现
前置条件	测试夹具、工厂、种子数据、模拟对象或设置 API
用户操作	公开 UI、CLI、HTTP、SDK 或原生交互
判定依据	可见状态、输出、响应、持久状态或发出的事件
清理	回滚事务、拆除测试夹具或隔离临时状态

选择能够覆盖该行为的最精简现有测试框架：

• Web 或桌面 UI：代码库的浏览器或 UI 测试运行器；
• API 或服务：原生集成测试客户端；
• CLI：现有子进程或命令运行器；
• 移动端：项目的原生 UI 测试框架；
• 库：通过当前测试运行器调用公开 API。

如果稳定的公开 API 测试能更直接地验证行为，就不要强行使用浏览器测试。

4. 编写确定性测试

按照周边代码的风格编写测试。保留以下可追溯性：

• 在测试名称或元数据中包含场景 ID；
• 在符合本地约定时，通过简短的代码注释链接到场景路径；
• 确保 Markdown 中的每项判定依据都有对应断言；
• 使用稳定的角色、标签、测试 ID、公开输出或 API 契约；
• 使用现有工厂、模拟对象、临时目录或事务隔离状态；
• 当时间、随机性、重试和网络调用会影响结果时，对其进行控制；
• 即使断言失败，也要确保执行清理。

不要盲目复制随附的演示代码。代码中的测试夹具是虚构的，仅用于展示映射关系，并非可复用的项目基础设施。

5. 验证编译结果

单独运行新测试。确认在安全且可行的情况下，如果没有相关行为或回归修复，测试会因预期原因失败。然后运行最相关的测试套件，以及仓库要求的 lint、类型检查、构建和测试命令。

从语义上检查失败。只有测试本身有误时才修正测试。除非用户要求实现或修复，否则不要更改产品行为。

检查以下内容：

• 每条 Markdown 判定标准都有对应的断言；
• 不会意外依赖在线服务、账户、付款或生产环境；
• 重复运行使用隔离状态，且顺序稳定；
• 失败输出能指出出错的行为；
• 场景与编译后的测试相互关联。

6. 移交证据

报告：

1. 测试设计依据的仓库证据；
2. 场景路径和编译后的测试路径；
3. 覆盖的行为和边界；
4. 运行的命令及结果；
5. 有意留给集成测试或冒烟测试覆盖的内容。

示例演示

• Web 工作区邀请搭配示例 Playwright 编译结果。
• 过期的 CLI 会话搭配示例 pytest 编译结果。

使用这些示例说明从 Markdown 到代码的转换模式。应用此技能时，所有命令、fixture 和断言都必须根据实际仓库得出。

失败处理

• 没有测试框架：记录最可行的切入点，并在添加依赖前征求同意。
• 行为未记录或相互矛盾：保留证据，并询问产品负责人哪种结果具有权威性。
• 失败需要主观判断或人工判断：将确定性部分保留为场景测试，其余部分交由冒烟测试覆盖。
• 经过两次针对性尝试后测试仍不稳定：停止尝试，保留日志，并报告未受控的输入，而不是添加重试。