apifox-test-case

API test case

Prerequisite: first read ../apifox-cli/SKILL.md. If the old general entry point conflicts with the domain rules of this skill, the current CLI help and this skill take precedence. When API definitions are involved, use commands such as endpoint, schema, and folder according to the current CLI help; when multi-step flows are involved, read ../apifox-test-scenario/SKILL.md。

Specific command parameters are subject to the current CLI help. When creating and updating API test cases, focus on the categoryId display risk, the boundary between test-case and test-scenario, the requestBody/processor/assertion/extractor structure, and the run verification boundary. Before writing, the Agent must use cli-schema validate to validate the payload, and after writing use get to read back and confirm the saved structure.

When to use

• Create automated test cases under an endpoint.
• Update test steps, assertions, extracted variables, and pre/post processors.
• View which test cases exist under a certain endpoint.
• Run API test cases by caseId, endpointId, or categoryId.
• Create or maintain test datasets.
• Troubleshoot "test steps cannot be displayed", "assertions do not take effect", and "extracted variables are empty".

Should not be used

• Multi-endpoint flow orchestration or test scenario modeling: go to apifox-test-scenario。
• Only run existing scenarios, suites, or CI commands: go to apifox-test-automation。
• Only modify API definitions, request parameters, or response models: use API design commands such as endpoint/schema according to the current CLI help.
• Only view test reports: use test-reportaccording to the current CLI help; for execution and report boundaries, refer to apifox-test-automation。

Core concepts

Concept	CLI resource	Description
API test case	test-case	Test data and steps bound to an endpoint
Test category	test-case category	Test case category; used before creating a case to obtain a valid categoryId
Test dataset	test-data	Data that can be used for iterative runs
API definition	endpoint	The dependency object of a case, not equivalent to the case itself
Test scenario	test-scenario	Multi-step flow orchestration, with a different boundary

Command entry points

Use the current CLI help to query the parameters of 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 by endpoint, use test-case list --endpoint <endpointId>；apifox run --test-case only accepts caseId.

When importing a single-endpoint case into a test scenario, do not hand-write scenario steps in this skill; go to apifox-test-scenario and use:

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

Standard process for creating a test case

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 endpoint, execute apifox test-case list --project <projectId> --endpoint <endpointId>。
4. If a similar case already exists, first apifox test-case list --project <projectId> --endpoint <endpointId>, then get one as a template.
5. Obtain and validate test-case-create schema。
6. Construct complete JSON; do not write only an empty shell with name/endpointId.
7. Immediately after creation test-case get <caseId>, confirm the actual structure saved by 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 a report, use test-report according to the current CLI help to check step details; if the report lacks details, refer to apifox-test-automation for the local/cloud report boundary.

categoryId is a key required field for the frontend to display test cases, not an ordinary optional category. Invalid categoryId may cause the CLI get/list to show the case, but it is invisible and not operable in the client's category list. Before creating, you must use test-case category to get a valid ID.

Standard process for updating test cases

When updating, you must first get the original structure and modify based on the complete structure, then validate the test-case-update schema to avoid losing existing steps, assertions, variable extractions, or processors.update is not JSON Patch and will not merge array elements by id.

test-case-create and test-case-update schemas already include pre/post processors, assertions, extracted variables, and enum value descriptions. When writing a processor for the first time, look at the schema first; do not guess field names, enum values, or old formats from experience. Current test-case-update will validate type according to processor data structure; for example extractor will validate variableType/subject/shareScope，assertion will validate subject/comparison，delay of data must be a number.

test-case get In the read-back structure, method may be an empty string; this does not mean the frontend method display is abnormal, as the client usually displays the HTTP method from the bound endpoint. Current test-case-update schema is already compatible with this read-back structure; when updating, do not reverse-guess the value to fill in method, unless the user explicitly wants to change the bound interface or request method.

Test step display rules

If the user cares about frontend display, you must additionally verify:

1. After creating or updating, execute test-case get。
2. to confirm that steps, assertions, extracted variables, and processor fields are saved by the backend.
3. Confirm that 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 project, branch, endpoint, categoryId, and the read-back structure are consistent.

Content and processor structure

• requestBody.data must be a string; do not write the JSON Body as an object.
• For multi-line JSON Body, pre-script, and post-script, use \n to pre-format; this only affects client display readability and does not change execution semantics.
• preProcessors、postProcessors uses a flat structure { id, type, data, defaultEnable, enable }, do not write the old-style nested { type, config }。
• Processors should carry a stable id, especially assertion、extractor、customScript; missing id may pass validate but cause parsing exceptions in the runner or client.
• When extracting global variables,data.variableType use globals; if you need to specify the effective scope,data.shareScope prefer to use PROJECT。TEAM is team scope and may depend on value-added capabilities; unless the user explicitly requests team scope, do not use it by default.
• Before writing, run cli-schema validateas usual; after writing, test-case get read back to confirm the saved structure.

Example:

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

For regular validation, prefer visual assertion; custom scripts are only a fallback capability.

Assertion rules:

• For routine validations such as HTTP status codes, JSON field existence/equality, and text contains, prefer the visual assertion; do not default to writing customScript。
• Visual assertion fields use the current schema enums: for HTTP status code use httpCode, do not use responseCode; for JSON fields use responseJson, do not use responseBody; for full-text contains use responseText + include; for comparison operators use equal, do not use equals。

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

Script rules:

• Use custom scripts only for logic that visual assertions cannot cover, such as complex array filtering, conditional checks, secondary requests, XML conversion, or schema validation.
• The Apifox script runtime reads and writes variables, accesses responses, and defines assertions through the pm object; script assertions are wrapped with pm.test(...) .
• Do not call pm.test nakedly outside of pm.response.json(), to avoid errors that are hard to locate 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 write only the case name and endpointId; this creates an empty shell that looks like it has no steps on the frontend.
• Do not use unverified categoryId。
• Do not judge that frontend display is abnormal only because the test-case get returned by method is empty; the client may display the HTTP method from the bound endpoint,test-case-update and the schema is also compatible with that read-back value.
• Do not guess the field names of processor/assertion/extractor based on experience.
• Do not use endpoint response in place of test-case assertion.
• Do not write a single-interface test-case as a multi-step scenario; test-case does not support data passing between scenario steps.
• Do not write inter-step passing rules such as {{$.1.response...}}、forEach from a scenario into a test-case; if a cross-step flow is needed, create or maintain test-scenario。
• If the user wants to reuse an existing test-case as a scenario step, use test-scenario import-steps --source test-case, and after importing, get --with-case-detail read it back and fill in the business parameter values.

Run rules

• test-case run <caseId> runs a single case.
• test-case run --endpoint <endpointId> runs the runnable cases under that interface for the interface.
• --category <categoryId> must be used together with --endpoint <endpointId> .
• apifox run --test-case <caseId> supports only caseId, not endpoint/category selector.
• --environment may be omitted, but it is recommended to specify it explicitly for reproducibility.
• After creating or updating, run at least once to confirm that requestBody, processors, assertions, and scripts actually take effect in the runner;cli-schema validate and test-case get succeeding does not mean it will definitely be correct at runtime.

Common recovery

Symptom	Handling
Test steps are not displayed	test-case get to see the real structure, and if necessary convert to apifox-cli-checkup
Assertions do not take effect	Read an existing successful case template and compare the assertion fields
Extracted variable is empty	Check the extractor level, variable name, response path, and execution report
run-config 404	Confirm that the case/endpoint/environment/branch all exist, then convert to apifox-cli-checkup
Case cannot be found under endpoint	Check whether the correct --branch and --endpoint