场景测试与报告

单个请求只能证明一次调用。场景测试证明的是一个工作流：一个有序的请求序列，其中一个响应中的值喂给后续请求，并在每一步检查断言。场景捕捉了原本只存在于开发者脑中的端到端流程。

场景包含什么

• 有序步骤，每一步引用规范中的一个操作；
• 步骤之间的数据传递——例如，从已创建资源取出 id 并在下一个请求中使用；
• 对状态码、响应头或响应字段的断言；
• 运行前读者必须提供的值。

顺序和断言是一等公民：执行期间从不会被悄悄丢弃。

运行场景

场景在主进程中通过来自 @powerduck/openapi-cli 的 runScenario 引擎执行：

• scenario:run 用场景、规范和请求配置启动一次运行；
• 步骤执行时进度通过 scenario:event 流式返回；
• scenario:cancel 停止正在运行的任务。

你可以观察每一步，看到流程在哪里失败，并取消长时间的运行。

助手如何构建场景

助手不会在规范内部凭空捏造测试定义。场景是独立的宿主工作流，从不会存储在 OpenAPI 文档中——不存在 x-scenarios 键或内嵌步骤。

当你要求既设计接口又测试它们时，工作会被排序：

1. 助手先只提出接口补丁；
2. 你应用后，它返回一张动作卡片来运行流程：
   • test.single 用于单个接口；
   • scenario.plan 让宿主发现端到端流程；
   • scenario.run 准备并运行一个有序流程。

一张 scenario.run 卡片按执行顺序（两到八个）列出操作并陈述目标，包括哪个响应字段、响应头或状态喂给每个后续请求。每个引用都从当前规范逐字复制。

报告

运行后，你可以导出一份自包含 HTML 报告。它是一份总结性文档，而不是原始 CLI 输出：它以可读的布局呈现流程、每步结果、断言和最终结果。

导出时选择一种语言。内置十种语言：

1. English
2. 简体中文（简体中文）
3. 繁體中文（繁体中文）
4. 日本語（日语）
5. 한국어（韩语）
6. Français（法语）
7. Deutsch（德语）
8. Español（西班牙语）
9. Português — Brasil（葡萄牙语-巴西）
10. العربية（阿拉伯语）

其他/自定义选项允许输入其他语言，但没有内置翻译时，报告界面文字会回退为英语；输入语言并不会自动翻译报告。

分享前请检查导出的报告：

• 已识别的凭据字段会自动脱敏，但任意正文、URL 和自定义字段仍可能包含敏感数据，请在分享前检查并移除；
• 大型正文以折叠方式显示，方便阅读。折叠内容并不会从导出的 HTML 中删除数据。

HTML 是独立的，因此可以附到工单或随版本归档。

何时使用场景

• 验证多步骤业务流程（创建、读取、更新、删除）；
• 确认认证和令牌传递在跨调用时正常工作；
• 为发布或交接产出 API 行为的证据；
• 在契约变更后对流程做回归检查。

相关：请求工作区、用助手进行设计、Mock 服务器。