apidog-test-scenario

测试场景建模

前置条件：先阅读 ../apidog-cli/SKILL.md。如果稳定入口技能与此领域技能冲突，请以当前 CLI 帮助和此技能为准。对于单端点用例，请阅读 ../apidog-test-case/SKILL.md；对于执行、CI 和报告边界，请阅读 ../apidog-test-automation/SKILL.md。环境和变量命令以当前 CLI 帮助为准。

始终使用当前 CLI 帮助确认确切参数。创建或更新测试场景时，重点关注步骤持久化语义、导入/引用边界、变量传递、复杂步骤字段风险和运行时验证。Agent 应优先使用导入/引用命令，并通过 get --with-case-detail 读取实际结构，再进行本地更新。

适用场景

• 创建或更新测试场景。
• 设计多步骤自动化流程，例如登录 -> 创建资源 -> 查询 -> 断言 -> 清理。
• 编排条件、循环、等待、脚本、数据库操作或外部程序等步骤类型。
• 处理前置/后置操作、变量引用、变量提取器和断言链。
• 诊断场景步骤关联失败、变量为空、步骤顺序错误，或创建场景后客户端显示异常等问题。

不适用场景

• 单端点测试用例：使用 apidog-test-case。
• 仅运行现有场景、测试套件或 CI 命令：使用 apidog-test-automation。
• 仅查看报告：使用当前 CLI 帮助中的 test-report；执行和报告边界请使用 apidog-test-automation。
• 仅配置环境、变量、数据库连接或类似运行时上下文：使用当前 CLI 帮助中的环境、变量、数据库连接及相关命令。

核心边界

概念	CLI 资源	说明
API 测试用例	test-case	绑定到一个端点的用例；适用于单端点验证
测试场景	test-scenario	多步骤工作流编排
测试套件	test-suite	用于回归测试的场景/用例集合
环境	environment	提供 baseUrl、变量和服务配置
测试数据	test-data	场景或用例的迭代数据源

命令入口

使用当前 CLI 帮助查看 test-scenario 参数。import-steps 和 add-ref 可能不会出现在顶级命令列表中，但两者均支持 --help，可用于导入步骤或添加场景引用。

重要事实：test-scenario create 只保存元数据。即使创建负载中包含 steps，创建时也不会保存这些步骤。正确流程是先创建元数据，然后运行 get --with-case-detail，再通过 import-steps、add-ref 或 test-scenario update --file 添加或修改步骤。

对于常见导入，优先使用高级导入命令。导入现有资源时，不要手写复杂的 HTTP 绑定结构。已验证的入口包括：

apidog test-scenario import-steps <scenarioId> --project <projectId> --source endpoint --ids <endpointIds> --sync manual
apidog test-scenario import-steps <scenarioId> --project <projectId> --source test-case --endpoint <endpointId> --ids <testCaseIds> --sync manual
apidog test-scenario import-steps <scenarioId> --project <projectId> --source test-scenario --from-scenario <sourceScenarioId> --step-ids <stepIds>
apidog test-scenario add-ref <scenarioId> --project <projectId> --scenario <sourceScenarioId>

语义边界：

• import-steps 会将步骤复制/导入到当前场景中。
• add-ref 会添加对另一个场景的引用；它不会复制源场景的内部步骤。
• --sync manual 是默认值，适用于导入的步骤需要业务参数、变量引用或断言的情况。
• --sync auto 仅适用于端点/测试用例来源，表示步骤与源 API 定义或单端点用例同步；测试场景来源不支持自动同步。
• CLI 命令为非交互式；缺少 ID 时不会自动列出所有资源。如果缺少端点、用例、场景或步骤 ID，请遵循 agentHints，先使用 list/get。

简化创建必须包含所有必需的元数据，但创建出的场景仍然为空。除非用户明确需要占位场景，否则创建自动化测试或场景不能止步于空场景。

标准建模流程

1. 明确业务目标：要验证什么流程、成功的标准是什么，以及失败后应如何清理。
2. 确认项目、分支和环境。
3. 列出涉及的端点、用例、环境变量、测试数据、数据库连接或脚本。
4. 如果在 AI 或 sprint 分支上创建场景，且只编辑场景本身，则无需选择被引用的端点或用例。只有在需要修改被引用的端点、单端点用例或源场景时，才选择资源。
5. 如果存在类似场景，使用 test-scenario list/get 读取并作为模板。
6. 先用自然语言设计步骤图，再将其转换为 JSON；不要猜测字段来编写。
7. 获取 test-scenario-create schema 并创建元数据。
8. 创建后，运行 test-scenario get --with-case-detail 读取完整结构。
9. 导入现有资源时，优先使用 import-steps 或 add-ref；不要手写复杂的绑定字段。
10. 导入后，再次运行 test-scenario get --with-case-detail，确认步骤已写入，且 HTTP 用例／详情可正确展开。
11. 导入 API 定义或测试用例后，检查参数、请求头、请求体和脚本变量是否只是 schema 示例；如有需要，使用 test-scenario update --file 更新为业务值。
12. 进行详细编辑时，获取 test-scenario-update schema，并修改完整的回读结构。
13. cli-schema validate 通过后，先更新，再运行 test-scenario get --with-case-detail，确认 steps 非空且结构正确。

test-scenario-update schema 包含步骤、前后置处理器、断言、提取器和枚举说明。首次编写处理器时，先阅读 schema；不要猜测字段名、枚举值或旧版格式。

步骤设计最佳实践

对于每个步骤，描述：

stepName: what this step does
stepType: which step type to use
input: request, script, SQL, wait condition, or referenced variables
output: variables to extract
assertions: success criteria
onError: continue, stop, or cleanup behavior
cleanup: whether post-run cleanup is needed

对于复杂流程，采用分层设计：

Prepare data
Authenticate/login
Main business operation
Query and assert result
Verify side effects
Clean up resources

数据传递与变量引用

• 创建前列出数据来源：环境变量、全局变量、上一步的请求／响应、迭代数据或脚本输出。
• 步骤间传递数据时，优先使用 Apidog 原生的上一步结果引用，例如 {{$.1.response.body.token}} 和 {{$.2.response.body.data.id}}。这些引用仅在完整的自动化场景运行中有效；单独运行某个步骤时无法解析。
• 如果同一值会在多个模块中重复使用，或需要稳定的名称，则将其提取为变量，并使用 {{token}} 引用。
• 随机后缀、临时标识符或非响应中生成的值适合作为环境变量，例如 pm.environment.set('runSuffix', suffix);。
• 在脚本中，不要直接为上一步的值编写 {{...}}；应使用 pm.variables.get("$.1.response.body.token")。
• 步骤引用取决于步骤 ID／编号。插入、删除或重新排序步骤后，重新检查每个 {{$.step...}} 引用。
• 不要假设响应路径始终是 body.data.id；应核实实际响应路径，例如 {{$.2.response.body.id}}、{{$.2.response.body.data.id}} 或 {{$.2.response.body.data[0].id}}。
• 在生成的负载中，准确保留 {{...}} 占位符。不要转义、拆分或改写它们，否则运行时替换会失败。
• 变量为空时，首先检查是否运行了完整场景、步骤 ID、JSONPath、响应结构、执行顺序和所选环境。

更新安全性

• 编辑现有步骤时，始终基于完整的 get --with-case-detail 回读结果进行更新。
• update 不是 JSON Patch，也不会按 ID 合并数组条目。
• 编辑现有结构时，保留步骤和处理器的稳定 ID。
• 对于现有的 HTTP／自定义／套接字步骤，除非有意修改，否则保留回读结果中的内部用例对象。
• 更新后，重新读取结果，并根据需要运行场景或进行有针对性的试运行。

常见问题恢复

症状	操作
场景已创建，但没有步骤	如果只使用了 create，这是预期行为；使用 import-steps、add-ref 或 update --file 添加步骤
导入的步骤使用了示例值	导入后，使用业务参数更新场景
变量为空	检查完整运行、步骤编号、响应路径、提取器和环境
客户端未显示步骤	使用 get --with-case-detail；确认步骤已保存且不为空
需要运行或检查报告	切换到 apidog-test-automation