apifox-test-automation

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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

Automated Test Execution, Suites & 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 场景下以退出码、报告文件和上传状态作为门禁依据。

Prerequisite: Read
../apifox-cli/SKILL.md
first. If there is a conflict between the old main entry and the domain rules of this skill, follow the current CLI help and this skill. For complex scenario step modeling, refer to
../apifox-test-scenario/SKILL.md
; for interface cases, refer to
../apifox-test-case/SKILL.md
. Commands related to environment, variables, and reports are subject to the current CLI help; the following focuses on execution boundaries and common pitfalls.

Specific command parameters are subject to the current CLI help. Before execution, focus on confirming resource boundaries, empty suite risks, runner/scheduled task constraints, CI report boundaries, and post-run troubleshooting sequence. In Agent scenarios, use the run result as the acceptance action; in CI scenarios, use the exit code, report file, and upload status as the gatekeeping basis.

何时使用

When to Use

创建、更新、运行测试套件。
运行已有测试场景。
配置定时任务或 CI 回归。
管理 runner 或检查 runner 状态。
需要
```
apifox run
```
的执行参数、reporters、迭代、变量覆盖、SSL、超时、报告上传。

Create, update, and run test suites.
Run existing test scenarios.
Configure scheduled tasks or CI regression.
Manage runners or check runner status.
Need execution parameters, reporters, iterations, variable overrides, SSL, timeout, and report upload for
```
apifox run
```
.

资源边界

Resource Boundaries

用户诉求	优先资源
单接口下的测试用例	`test-case` ，转 `apifox-test-case`
多步骤业务流程建模	`test-scenario` ，转 `apifox-test-scenario`
多场景集合回归	`test-suite`
定时执行	`scheduled-task`
私有执行机	`runner`
查看执行结果	`test-report` ，按当前 CLI help 查询或下载报告

User Requirement	Priority Resource
Test cases under a single interface	`test-case` , redirect to `apifox-test-case`
Multi-step business process modeling	`test-scenario` , redirect to `apifox-test-scenario`
Regression of multi-scenario collections	`test-suite`
Scheduled execution	`scheduled-task`
Private execution machine	`runner`
View execution results	`test-report` , query or download reports according to current CLI help

命令入口

Command Entry

使用当前 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 当成项目内轻量资源随手创建。

Use the current CLI help to query parameters for

test-suite

scheduled-task

runner

, and

run

run --help

covers parameters such as reporters, out-dir, upload-report, iteration, variable overrides, SSL, timeout, and

--carry-runtime-variables

test-suite create --name

will create an empty suite, which can be displayed on the client but has

items: []

. Unless the user explicitly requests a placeholder suite, "creating a regression suite/automation suite" must add items via

--file

or subsequent update, and verify that

items

is not empty via

get

Non-empty suites should use the frontend-compatible structure in

cli-schema get test-suite-create

, such as

STATIC_TEST_CASE

testCases[].id

to reference existing test cases. Do not use legacy shorthand, such as

{ testScenarioId }

which will be intentionally blocked by schema validation.

Runner is a team-level execution resource. Before creation, the team and usage must be confirmed. Currently, the commonly used combination is

runnerType=GENERAL

serverType=SELF_HOSTED

. Do not treat runner as a lightweight resource within the project and create it casually.

创建/更新规则

Creation/Update Rules

复杂测试场景创建/更新请使用

apifox-test-scenario

。

定时任务创建不要给空壳示例。虽然 schema required 可能只标

name/cronExpression/runOn

，真实可用任务通常还需要有效 runner、

TEST_SUITE

entityId 等上下文；

runOn

仅限当前 CLI help/schema 支持值，例如

APP/TSHGR/OSHGR

，不要写未支持的

CLOUD

。

更新前必须先

get

原始结构，避免覆盖步骤、变量、场景引用或套件成员。

For complex test scenario creation/update, use

apifox-test-scenario

Do not provide empty shell examples when creating scheduled tasks. Although schema required may only mark

name/cronExpression/runOn

, a usable task usually requires valid contexts such as effective runner and

TEST_SUITE

entityId;

runOn

is limited to values supported by the current CLI help/schema, such as

APP/TSHGR/OSHGR

, do not write unsupported

CLOUD

Before updating, you must first

get

the original structure to avoid overwriting steps, variables, scenario references, or suite members.

运行参数

Running Parameters

常见运行参数以

apifox run --help

和具体 run 命令 help 为准。CI 场景重点确认 environment、reporters、out-dir、upload-report、iteration、变量覆盖、超时、bigint 和是否需要

--carry-runtime-variables

。

建议 CI 最小命令形态：

bash

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

Common running parameters are subject to

apifox run --help

and specific run command help. In CI scenarios, focus on confirming environment, reporters, out-dir, upload-report, iteration, variable overrides, timeout, bigint, and whether

--carry-runtime-variables

is needed.

Recommended minimal CI command format:

bash

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

执行后动作

Post-Execution Actions

本地报告：检查
```
--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 注入，不要写入仓库。

Local report: Check
```
--out-dir
```
and
```
--out-file
```
.
Cloud report: Only after running with
```
--upload-report
```
, execute
```
test-report list/get/download
```
according to the current CLI help.
Failure troubleshooting: First check CLI output, JSON report, agentHints, then locate the specific scenario/suite/case.
When
```
--upload-report
```
is not used, the result of this local execution will not appear in the cloud
```
test-report list
```
.
In CI, it is recommended to explicitly specify
```
--environment
```
, inject tokens using CI secrets, and do not write them into the repository.

常见恢复

Common Recovery

现象	处理
创建场景后步骤不对	转 `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`

Phenomenon	Handling
Incorrect steps after scenario creation	Redirect to `apifox-test-scenario` ; confirm whether steps are updated after creation
Empty suite run	Use `test-suite get` to confirm included scenarios/cases
Suite `items: []`	This is an empty placeholder suite, not a valid regression suite
CI cannot find the environment	Use `environment list/get` according to current CLI help to confirm environmentId
Runner unavailable	Run `runner check` , then check runner get/list
Report lacks step details	First distinguish between local JSON, cloud upload, and download interface summaries, then redirect to `apifox-cli-checkup` if necessary