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

.

cli-schema validate

get

• 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'.

• 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.

1. Confirm the project and branch.
2. Locate the endpoint:

   apifox endpoint list/get

   .
3. 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>

   .
4. If similar cases exist, first run

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

   , then

   get

   one as a template.
5. Obtain and verify the

   test-case-create

   schema.
6. Construct a complete JSON, do not only write empty name/endpointId.
7. Immediately run

   test-case get <caseId>

   after creation to confirm the actual saved structure on the backend.
8. Run once and generate a local JSON report to confirm that requestBody, processors, assertions and scripts actually take effect in the runner.
9. 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

categoryId

get/list

test-case category

1. Execute

   test-case get

   after creation or update.
2. Confirm that steps, assertions, variable extraction, and processor fields are saved by the backend.
3. Confirm that the fields are not empty arrays, empty objects, or written to the wrong level.
4. 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.

• 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.

{
  "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

• 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

  .

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

• 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);
});

• 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.

• 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.