API Test Cases

Prerequisites: 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. When involving interface definitions, use commands like endpoint, schema, folder according to the current CLI help; when involving multi-step processes, read
../apifox-test-scenario/SKILL.md
.

Refer to the current CLI help for specific command parameters. When creating and updating API test cases, focus on handling risks related to categoryId display, boundaries between test-case and test-scenario, structures of requestBody/processor/assertion/extractor, and boundaries of operation verification. The Agent must use

cli-schema validate

to verify the payload before writing, and use

get

to read back and confirm the saved structure after writing.

When to Use

Create automated test cases under an API.
Update test steps, assertions, variable extraction, pre/post processors.
Check which test cases exist under a specific endpoint.
Run API test cases by caseId, endpointId, or categoryId.
Create or maintain test datasets.
Troubleshoot issues like 'test steps not displaying', 'assertions not taking effect', 'variable extraction returns empty'.

When Not to Use

Multi-API process orchestration or test scenario modeling: Switch to
```
apifox-test-scenario
```
.
Only run existing scenarios, suites or CI commands: Switch to
```
apifox-test-automation
```
.
Only modify API definitions, request parameters or response models: Use API design commands like endpoint/schema according to the current CLI help.
Only view test reports: Use
```
test-report
```
according to the current CLI help; refer to
```
apifox-test-automation
```
for boundaries between execution and reports.

Core Concepts

Concept	CLI Resource	Description
API Test Case	`test-case`	Test data and steps bound to an API endpoint
Test Category	`test-case category`	Test case category; used to obtain valid `categoryId` before creating a case
Test Dataset	`test-data`	Data available for iterative runs
API Definition	`endpoint`	Dependent object of a case, not equivalent to the case itself
Test Scenario	`test-scenario`	Multi-step process orchestration with different boundaries

Command Entry Points

Use the current CLI help to query parameters for

test-case

test-data

and

apifox run --test-case

test-case category

is used to obtain

categoryId

; the current

test-case category

does not support

--endpoint

. To view existing cases under an API, use

test-case list --endpoint <endpointId>

;

apifox run --test-case

only accepts caseId.

When importing single-API cases into test scenarios, do not manually write scenario steps in this skill; switch to

apifox-test-scenario

and use:

bash

apifox test-scenario import-steps <scenarioId> --project <projectId> --source test-case --endpoint <endpointId> --ids <testCaseIds> --sync manual

Standard Process for Creating Test Cases

Confirm the project and branch.
Locate the endpoint:
```
apifox endpoint list/get
```
.

Must execute

apifox test-case category --project <projectId>

to obtain a valid

categoryId

; if you need to view existing cases under an API, execute

apifox test-case list --project <projectId> --endpoint <endpointId>

If similar cases exist, first run

apifox test-case list --project <projectId> --endpoint <endpointId>

, then

get

one as a template.

Obtain and verify the
```
test-case-create
```
schema.
Construct a complete JSON, do not only write empty name/endpointId.
Immediately run
```
test-case get <caseId>
```
after creation to confirm the actual saved structure on the backend.
Run once and generate a local JSON report to confirm that requestBody, processors, assertions and scripts actually take effect in the runner.
If uploading the report, use
```
test-report
```
according to the current CLI help to check step details; if the report lacks details, refer to the local/cloud report boundaries in
```
apifox-test-automation
```
.

categoryId

is a key required field for frontend display of test cases, not an optional category. An invalid

categoryId

may cause cases to be visible in CLI

get/list

, but invisible and unoperable in the client category list. Must obtain a valid ID using

test-case category

before creation.

Standard Process for Updating Test Cases

When updating, must first

get

the original structure and modify based on the complete structure, then verify the

test-case-update

schema to avoid losing existing steps, assertions, variable extraction or processors.

update

is not a JSON Patch, nor will it merge array elements by id.

The

test-case-create

and

test-case-update

schemas already include descriptions of pre/post processors, assertions, variable extraction and enumeration values. When writing a processor for the first time, check the schema first, do not guess field names, enumeration values or old formats based on experience. The current

test-case-update

will verify the

data

structure according to the processor

type

; for example,

extractor

will verify

variableType/subject/shareScope

assertion

will verify

subject/comparison

, and the

data

delay

must be a number.

The

method

in the structure read back by

test-case get

may be an empty string; this does not indicate an abnormal method display on the frontend, as the client usually displays the HTTP method from the bound endpoint. The current

test-case-update

schema is compatible with this read-back structure, do not reverse-guess the value to fill the method during update unless the user explicitly wants to modify the bound API or request method.

Display Rules for Test Steps

If the user cares about frontend display, additional verification must be performed:

Execute
```
test-case get
```
after creation or update.
Confirm that steps, assertions, variable extraction, and processor fields are saved by the backend.
Confirm that the fields are not empty arrays, empty objects, or written to the wrong level.
If the CLI returns success but the frontend does not display, switch to
```
apifox-cli-checkup
```
and first confirm whether the project, branch, endpoint, categoryId and read-back structure are consistent.

Content and Processor Structures

```
requestBody.data
```
must be a string, do not write JSON Body as an object.
Multi-line JSON Body, pre-scripts and post-scripts are pre-formatted with
```
\n
```
; this only affects readability in the client, not execution semantics.

preProcessors

and

postProcessors

use a flat structure

{ id, type, data, defaultEnable, enable }

, do not use the old nested structure

{ type, config }

It is recommended to include a stable
```
id
```
for processors, especially
```
assertion
```
,
```
extractor
```
,
```
customScript
```
; missing
```
id
```
may pass validation but cause parsing exceptions in the runner or client.
When extracting global variables, use
```
globals
```
for
```
data.variableType
```
; if you need to specify the effective scope, prefer
```
PROJECT
```
for
```
data.shareScope
```
.
```
TEAM
```
is a team-wide scope and may depend on value-added capabilities, do not use it by default unless the user explicitly requests team-wide scope.
Run
```
cli-schema validate
```
as usual before writing, and use
```
test-case get
```
to read back and confirm the saved structure after writing.

Example:

json

{
  "requestBody": {
    "type": "application/json",
    "data": "{\n  \"name\": \"Demo\",\n  \"description\": \"Readable in client\"\n}"
  },
  "postProcessors": [
    {
      "id": "postProcessors.0.customScript",
      "type": "customScript",
      "data": "pm.test('返回 ID', function () {\n  var body = pm.response.json();\n  pm.expect(body.data.id).to.exist;\n});",
      "defaultEnable": true,
      "enable": true
    },
    {
      "id": "postProcessors.1.extractor",
      "type": "extractor",
      "data": {
        "variableName": "project_pet_name",
        "variableType": "globals",
        "shareScope": "PROJECT",
        "subject": "responseJson",
        "expression": "$.name"
      },
      "defaultEnable": true,
      "enable": true
    }
  ]
}

Assertion and Script Rules

Prioritize using visual

assertion

for regular checks, and only use custom scripts as a fallback.

Assertion Rules:

For regular checks such as HTTP status code, JSON field existence/equality, text inclusion, prioritize using visual
```
assertion
```
, do not default to writing
```
customScript
```
.
Use current schema enumerations for visual assertion fields: use
```
httpCode
```
for HTTP status codes, not
```
responseCode
```
; use
```
responseJson
```
for JSON fields, not
```
responseBody
```
; use
```
responseText
```
+
```
include
```
for full-text inclusion; use
```
equal
```
for comparison operators, not
```
equals
```
.

json

{
  "type": "assertion",
  "data": {
    "name": "HTTP 状态码为 200",
    "subject": "httpCode",
    "comparison": "equal",
    "value": "200",
    "path": ""
  },
  "defaultEnable": true,
  "enable": true
}

Script Rules:

Custom scripts are only used for logic that cannot be covered by visual assertions, such as complex array filtering, conditional judgment, secondary requests, XML conversion or schema validation.
Apifox scripts use the
```
pm
```
object to read/write variables, access responses and define assertions during runtime; script assertions are wrapped with
```
pm.test(...)
```
.
Do not call
```
pm.response.json()
```
outside
```
pm.test
```
to avoid difficult-to-locate errors caused by empty responses or non-JSON responses.
Do not extend runtime context fields based on experience.

pm.environment.set("variable_key", "variable_value");
pm.variables.set("variable_key", "variable_value");

pm.test("Status code is 200", function () {
  pm.response.to.have.status(200);
});

pm.test("JSON value equals expected", function () {
  var jsonData = pm.response.json();
  pm.expect(jsonData.value).to.eql(100);
});

Field Risk Reminders

Do not write the step structure of
```
test-scenario
```
into
```
test-case
```
.
Do not only write the case name and endpointId, which will form an empty shell with no steps visible on the frontend.
Do not use unverified
```
categoryId
```
.
Do not judge frontend display exceptions solely based on the empty
```
method
```
returned by
```
test-case get
```
; the client may display the HTTP method from the bound endpoint, and the
```
test-case-update
```
schema is also compatible with this read-back value.
Do not guess field names of processor/assertion/extractor based on experience.
Do not use endpoint response instead of test-case assertion.
Do not write single-API test-case as a multi-step scenario; test-case does not support data transfer between scenario steps.
Do not write inter-step transfer rules like
```
{{$.1.response...}}
```
or
```
forEach
```
from scenarios into test-case; if cross-step processes are needed, create or maintain
```
test-scenario
```
.
If the user wants to reuse existing test-case as scenario steps, use
```
test-scenario import-steps --source test-case
```
, then read back with
```
get --with-case-detail
```
and fill in business parameter values after import.

Operation Rules

```
test-case run <caseId>
```
runs a single case.
```
test-case run --endpoint <endpointId>
```
runs runnable cases under the specified API.

--category <categoryId>

must be used together with

--endpoint <endpointId>

```
apifox run --test-case <caseId>
```
only supports caseId, not endpoint/category selector.
```
--environment
```
can be omitted, but it is recommended to specify it explicitly for reproducibility.
Run at least once after creation or update to confirm that requestBody, processors, assertions and scripts actually take effect in the runner; success in
```
cli-schema validate
```
and
```
test-case get
```
does not guarantee correctness during runtime.

Common Troubleshooting

Phenomenon	Handling
Test steps not displaying	Check the actual structure with `test-case get` , switch to `apifox-cli-checkup` if necessary
Assertions not taking effect	Read existing successful case templates and compare assertion fields
Variable extraction returns empty	Check extractor level, variable name, response path and execution report
run-config 404	Confirm that case/endpoint/environment/branch all exist, then switch to `apifox-cli-checkup`
Cannot find case under endpoint	Check if the correct `--branch` and `--endpoint` are specified

apifox-test-case

NPX Install

Tags

SKILL.md Content (Chinese)