自动化测试执行、套件与 CI
前置条件：先阅读
../apifox-cli/SKILL.md。若旧总入口与本 skill 的领域规则冲突，以当前 CLI help 和本 skill 为准。涉及复杂场景步骤建模时读取../apifox-test-scenario/SKILL.md，涉及接口 case 时读取../apifox-test-case/SKILL.md。环境、变量、报告相关命令以当前 CLI help 为准；下面重点说明执行边界和常见坑。
具体命令参数以当前 CLI help 为准。执行前重点确认资源边界、空套件风险、runner/定时任务约束、CI 报告边界和运行后排查顺序。Agent 场景下把 run 结果作为验收动作；CI 场景下以退出码、报告文件和上传状态作为门禁依据。
何时使用
- 创建、更新、运行测试套件。
- 运行已有测试场景。
- 配置定时任务或 CI 回归。
- 管理 runner 或检查 runner 状态。
- 需要
apifox run的执行参数、reporters、迭代、变量覆盖、SSL、超时、报告上传。
资源边界
| 用户诉求 | 优先资源 |
|---|---|
| 单接口下的测试用例 | test-case，转 apifox-test-case |
| 多步骤业务流程建模 | test-scenario，转 apifox-test-scenario |
| 多场景集合回归 | test-suite |
| 定时执行 | scheduled-task |
| 私有执行机 | runner |
| 查看执行结果 | test-report，按当前 CLI help 查询或下载报告 |
命令入口
使用当前 CLI help 查询 test-suite、scheduled-task、runner 和 run 的参数。run --help 覆盖 reporters、out-dir、upload-report、iteration、变量覆盖、SSL、超时和 --carry-runtime-variables 等参数。
test-suite create --name 会创建空套件，客户端可展示但 items: []。除非用户明确要占位套件，否则“创建回归套件/自动化套件”必须通过 --file 或后续 update 加入 items，并 get 验证 items 非空。
非空套件应使用 cli-schema get test-suite-create 中的前端兼容结构，例如 STATIC_TEST_CASE + testCases[].id 引用已有测试用例。不要使用 legacy shorthand，例如 { testScenarioId } 这类会被 schema validate 故意拦截的写法。
Runner 是团队级执行资源，创建前必须确认团队和用途。当前实际常用组合是 runnerType=GENERAL、serverType=SELF_HOSTED，不要把 runner 当成项目内轻量资源随手创建。
创建/更新规则
复杂测试场景创建/更新请使用 apifox-test-scenario。
定时任务创建不要给空壳示例。虽然 schema required 可能只标 name/cronExpression/runOn，真实可用任务通常还需要有效 runner、TEST_SUITE entityId 等上下文；runOn 仅限当前 CLI help/schema 支持值，例如 APP/TSHGR/OSHGR，不要写未支持的 CLOUD。
更新前必须先 get 原始结构，避免覆盖步骤、变量、场景引用或套件成员。
运行参数
常见运行参数以 apifox run --help 和具体 run 命令 help 为准。CI 场景重点确认 environment、reporters、out-dir、upload-report、iteration、变量覆盖、超时、bigint 和是否需要 --carry-runtime-variables。
建议 CI 最小命令形态：
apifox test-suite run <suiteId> --project <projectId> --environment <environmentId> --reporters cli,json,junit --upload-report执行后动作
- 本地报告：检查
--out-dir和--out-file。 - 云端报告：仅在运行时带
--upload-report后，按当前 CLI help 执行test-report list/get/download。 - 失败排查：先看 CLI 输出、JSON report、agentHints，再定位到具体 scenario/suite/case。
- 不带
--upload-report时，云端test-report list不会出现本次本地执行结果。 - CI 中建议显式指定
--environment，token 使用 CI secret 注入，不要写入仓库。
常见恢复
| 现象 | 处理 |
|---|---|
| 创建场景后步骤不对 | 转 apifox-test-scenario；确认 create 后是否 update steps |
| 套件运行为空 | test-suite get 确认包含的场景/用例 |
套件 items: [] | 这是空占位套件，不是有效回归套件 |
| CI 找不到环境 | 按当前 CLI help 使用 environment list/get 确认 environmentId |
| runner 不可用 | runner check，再看 runner get/list |
| 报告没有步骤详情 | 先区分本地 JSON、云端上传、下载接口概要，再必要时转 apifox-cli-checkup |
