Menu
Apifox 自动化测试执行、套件与 CI：test-suite、scheduled-task、runner、apifox run、执行参数、迭代数据、报告上传和 CI 回归。复杂 test-scenario 步骤建模请使用 apifox-test-scenario。
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
Apifox 分支协作：普通分支、迭代分支、AI 分支、pick-to、merge、merge-request、保护分支、AI 写入权限与分支资源变更流程。用户要在分支上修改资源、创建 AI 分支或合并改动时使用。
Apifox CLI 使用检查与版本确认：命令成功但页面没看到、创建后 list/get 找不到、测试运行失败、报告缺失、agentHints/help/实际行为不一致，或怀疑本机 CLI 版本不是最新时使用。
通过 Apifox CLI 管理 Apifox 项目资源。触发场景：运行接口自动化测试/测试套件，查询/创建/更新/删除接口、环境、Schema、Mock、分支等项目资源，导入导出 API 文档，查看测试报告，管理 Runner、定时任务、通知等 CI/CD 配置。CLI 输出为结构化 JSON，常含 agentHints.nextSteps；所有命令支持 --help。
Apifox 导入导出与质量门禁：导入 OpenAPI/Postman/Apifox 原生格式，导出 OpenAPI/HTML/Markdown/Postman/Apifox 原生格式；导入前校验 spec 完整性、tags 分组、schema/body 覆盖率，导入后验证计数、模块和资源可见性。
Apifox 接口测试用例：test-case 与 test-data 的查询、创建、更新、删除、分类和运行；处理测试步骤、断言、提取变量、前后置处理器、数据集，以及“CLI 创建后前端测试步骤无法展示”等问题。
Apifox 测试场景建模：test-scenario 的查询、创建、更新、删除和运行；导入接口、单接口用例或其它场景步骤；添加场景引用步骤；复杂步骤编排、接口步骤/条件/循环/等待/脚本/数据库等步骤衔接、前后置操作、变量引用、断言、提取器和场景调试最佳实践。用户要创建或维护复杂自动化测试流程时使用。
| name | apifox-test-automation |
| description | Apifox 自动化测试执行、套件与 CI：test-suite、scheduled-task、runner、apifox run、执行参数、迭代数据、报告上传和 CI 回归。复杂 test-scenario 步骤建模请使用 apifox-test-scenario。 |
| metadata | {"requires":{"bins":["apifox"]},"cliHelp":"apifox test-scenario --help; apifox test-suite --help; apifox run --help"} |
前置条件：先阅读
../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 场景下以退出码、报告文件和上传状态作为门禁依据。
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。--upload-report 时，云端 test-report list 不会出现本次本地执行结果。--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 |