Prerequisites: first read
../apifox-cli/SKILL.md. If the old general entry point conflicts with this skill's domain rules, the current CLI help and this skill take precedence. When complex scenario step modeling is involved, read../apifox-test-scenario/SKILL.md; when interface cases are involved, read../apifox-test-case/SKILL.md. For environment, variable, and report-related commands, the current CLI help takes precedence; the following focuses on execution boundaries and common pitfalls.
For specific command parameters, the current CLI help takes precedence. Before execution, focus on confirming resource boundaries, empty-suite risks, runner/scheduled-task constraints, CI report boundaries, and the post-run troubleshooting order. In Agent scenarios, treat the run result as the acceptance action; in CI scenarios, use the exit code, report file, and upload status as the gate criteria.
When to Use
- Create, update, and run test suites.
- Run existing test scenarios.
- Configure scheduled tasks or CI regression.
- Manage runners or check runner status.
- When you need
apifox run's execution parameters, reporters, iterations, variable overrides, SSL, timeouts, and report upload.
Resource Boundaries
| User Request | Preferred Resource |
|---|---|
| Test cases under a single interface | test-case, switch to apifox-test-case |
| Multi-step business process modeling | test-scenario, switch to apifox-test-scenario |
| Multi-scenario collection regression | test-suite |
| Scheduled execution | scheduled-task |
| Private execution machine | runner |
| View execution results | test-report, query or download reports according to the current CLI help |
Command Entry Points
Use the current CLI help to query the parameters of 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 creates an empty suite; the client can display it but items: []. Unless the user explicitly wants a placeholder suite, "create a regression suite/automation suite" must add items through --file or a subsequent update, and get verify that items is non-empty.
A non-empty suite should use the frontend-compatible structure in cli-schema get test-suite-create , for example STATIC_TEST_CASE + testCases[].id to reference existing test cases. Do not use legacy shorthand, such as { testScenarioId } -style syntax, which is intentionally blocked by schema validate.
A Runner is a team-level execution resource; before creating one, you must confirm the team and purpose. The currently commonly used combination is runnerType=GENERAL、serverType=SELF_HOSTED; do not casually create runners as if they were lightweight resources within a project.
Create/Update Rules
For complex test scenario creation/updates, use apifox-test-scenario。
Do not provide empty-shell examples for scheduled task creation. Although schema required may only mark name/cronExpression/runOn, a truly usable task usually also needs a valid runner,TEST_SUITE entityId, and other context;runOn is limited to values supported by the current CLI help/schema, for example 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.
Run Parameters
For common run parameters, use apifox run --help Refer to the 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。
Recommended minimal CI command form:
apifox test-suite run <suiteId> --project <projectId> --environment <environmentId> --reporters cli,json,junit --upload-report
Post-execution actions
- Local report: check
--out-dirand--out-file。 - Cloud report: only after running with
--upload-report, execute per the current CLI helptest-report list/get/download。 - Failure troubleshooting: first check CLI output, JSON report, agentHints, then locate the specific scenario/suite/case.
- Without
--upload-report, the cloudtest-report listwill not show this local execution result. - In CI, it is recommended to explicitly specify
--environment; inject the token using CI secrets, do not write it into the repository.
Common recoveries
| Symptom | Handling |
|---|---|
| Steps are incorrect after creating a scenario | Switch to apifox-test-scenario; confirm whether steps are updated after create |
| Suite run is empty | test-suite get confirm the included scenarios/cases |
Suite items: [] |
This is an empty placeholder suite, not a valid regression suite |
| CI cannot find the environment | Use per the current CLI help environment list/get confirm environmentId |
| runner unavailable | runner check, then check runner get/list |
| Report has no step details | First distinguish local JSON, cloud upload, and download API summary, then switch to if necessary apifox-cli-checkup |