apidog-test-automation

测试自动化、测试套件与 CI

前置条件：先阅读 ../apidog-cli/SKILL.md。如果稳定版入口技能与此领域技能冲突，请以当前 CLI 帮助和此技能为准。对于复杂场景步骤建模，请阅读 ../apidog-test-scenario/SKILL.md；对于单接口用例，请阅读 ../apidog-test-case/SKILL.md。环境、变量和报告命令以当前 CLI 帮助为准。此技能侧重于执行边界和常见陷阱。

具体参数始终以当前 CLI 帮助为准。执行前，请确认资源边界、空测试套件风险、运行器／计划任务限制、CI 报告边界以及运行后的诊断顺序。在 Agent 工作流中，将运行结果视为验收检查。在 CI 中，将退出代码、报告文件和上传状态作为门禁条件。

适用场景

• 创建、更新或运行测试套件。
• 运行现有测试场景。
• 配置计划任务或 CI 回归测试。
• 管理运行器或检查运行器状态。
• 使用 apidog run 参数、报告器、迭代、变量覆盖、SSL、超时、报告上传或 --carry-runtime-variables。

资源边界

用户意图	首选资源
单接口测试用例	test-case；切换到 apidog-test-case
多步骤业务流程	test-scenario；切换到 apidog-test-scenario
多场景回归测试集合	test-suite
计划执行	scheduled-task
私有执行机器	runner
查看执行结果	test-report；根据当前 CLI 帮助查询或下载

命令入口

使用当前 CLI 帮助了解 test-suite、scheduled-task、runner 和 run 的参数。run --help 涵盖报告器、out-dir、upload-report、迭代、变量覆盖、SSL、超时和 --carry-runtime-variables。

test-suite create --name 会创建一个空测试套件。客户端可以显示它，但 items: [] 表示它不是可用的回归测试套件。除非用户明确需要占位测试套件，否则创建回归或自动化测试套件时，必须使用 --file 或通过后续更新添加条目，然后使用 get 确认 items 非空。

非空测试套件应使用与前端兼容的结构，该结构可通过 cli-schema get test-suite-create 获取，例如使用 STATIC_TEST_CASE，并通过 testCases[].id 引用。不要使用 { testScenarioId } 等旧版简写；架构验证会有意拒绝此类写法。

运行器是团队级执行资源。创建前请确认团队和用途。常见的实用组合是 runnerType=GENERAL 和 serverType=SELF_HOSTED；不要将运行器视为轻量级的项目本地资源。

创建和更新规则

复杂的测试场景创建或更新请使用 apidog-test-scenario。

不要根据空示例创建计划任务。即使架构中的必填字段看起来只有 name/cronExpression/runOn，可用的任务通常还需要有效的运行器和 TEST_SUITE 类型的 entityId 等上下文信息。runOn 必须使用当前 CLI 帮助／架构支持的值，例如 APP/TSHGR/OSHGR；不要填写 CLOUD 等不受支持的值。

更新前，始终先使用 get 获取原始结构，以免覆盖步骤、变量、场景引用或测试套件成员。

运行参数

使用 apidog run --help 和具体运行命令的帮助获取当前参数。CI 工作流应明确确认环境、报告器、out-dir、upload-report、迭代、变量覆盖、超时、大整数行为，以及是否需要 --carry-runtime-variables。

建议的最简 CI 命令形式：

apidog test-suite run <suiteId> --project <projectId> --environment <environmentId> --reporters cli,json,junit --upload-report

执行后

• 本地报告：检查 --out-dir 和 --out-file。
• 云端报告：仅在使用 --upload-report 运行后才会显示；然后查看当前 test-report list/get/download 帮助。
• 故障诊断：从 CLI 输出、JSON 报告和 agentHints 入手，然后定位具体场景、套件或用例。
• 如果未使用 --upload-report，云端 test-report list 中不会包含此次本地运行。
• 在 CI 中，明确指定 --environment；通过 CI 密钥注入令牌，切勿将其提交到代码库。

常见问题恢复

症状	操作
创建后场景步骤有误	切换到 apidog-test-scenario；确认创建后是否更新了步骤
套件运行结果为空	使用 test-suite get 并确认已包含的场景/用例
套件的 items: []	这是一个空占位项，不是有效的回归套件
CI 找不到环境	根据当前 CLI 帮助使用 environment list/get 确认 environmentId
Runner 不可用	运行 runner check，然后检查 runner get/list
报告没有步骤详情	区分本地 JSON、云端上传和下载的摘要；必要时切换到 apidog-cli-checkup