apifox-test-automation

自动化测试执行、套件与 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