Prerequisites: Read

../apifox-cli/SKILL.md

first. If the old main entry conflicts with the domain rules of this skill, follow the current CLI help and this skill. Refer to

../apifox-test-case/SKILL.md

when single-interface cases are involved, and

../apifox-test-automation/SKILL.md

when execution/CI/report boundaries are involved. Environment and variable commands are subject to the current CLI help.

get --with-case-detail

• Create or update test scenarios.
• Design multi-step automated workflows, such as Login -> Create Resource -> Query -> Assert -> Cleanup.
• Orchestrate multiple step types, conditional branches, loops, waits, scripts, database operations or external programs.
• Handle pre/post operations, variable references, variable extraction, assertion chains.
• Troubleshoot failures in step connection, empty variables, incorrect step order, abnormal front-end display after scenario creation.

• Test cases under a single interface: Switch to

  apifox-test-case

  .
• Only run existing scenarios, suites or CI commands: Switch to

  apifox-test-automation

  .
• Only view reports: Use

  test-report

  according to current CLI help; refer to

  apifox-test-automation

  for execution and report boundaries.
• Only configure environments, variables, database connections: Use commands like environment, variables, database-connection according to current CLI help.

test-scenario

import-steps

add-ref

--help

test-scenario create

steps

get --with-case-detail

import-steps

add-ref

test-scenario update --file

apifox test-scenario import-steps <scenarioId> --project <projectId> --source endpoint --ids <endpointIds> --sync manual
apifox test-scenario import-steps <scenarioId> --project <projectId> --source test-case --endpoint <endpointId> --ids <testCaseIds> --sync manual
apifox test-scenario import-steps <scenarioId> --project <projectId> --source test-scenario --from-scenario <sourceScenarioId> --step-ids <stepIds>
apifox test-scenario add-ref <scenarioId> --project <projectId> --scenario <sourceScenarioId>

• import-steps

  copies/imports steps as part of the current scenario.

• add-ref

  adds a step that references another scenario without copying the internal steps of the source scenario.

• --sync manual

  is the default mode, suitable for supplementing business parameters, variable references and assertions after import.

• --sync auto

  only applies to endpoint/test-case sources, indicating automatic synchronization with the source interface definition or single-interface test case; it is not supported for test-scenario sources.
• CLI is a non-interactive command and will not automatically list all resources when IDs are missing; when endpoint, case, scenario or step IDs are missing, follow agentHints to first list/get to locate them.

1. Clarify business objectives: What process to verify, what are the success conditions, how to clean up in case of failure.
2. Confirm project, branch, environment.
3. List involved endpoints, cases, environment variables, test data, database connections or scripts.
4. If creating scenarios in AI branches or iterative branches, there is no need to pick referenced interfaces or cases first when only adjusting the scenario itself; only when modifying referenced interfaces, single-interface test cases or the source scenario itself, pick the required resources from the main branch or corresponding source iterative branch to the current branch.
5. If there are similar existing scenarios, first use

   test-scenario list/get

   to read them as templates.
6. Design the step diagram in natural language first, then convert it to JSON; do not write while guessing fields.
7. Obtain the

   test-scenario-create

   schema to create metadata.
8. After creation, use

   test-scenario get --with-case-detail

   to read back the complete structure.
9. When importing existing resources, prioritize using

   import-steps

   or

   add-ref

   instead of writing complex binding fields directly.
10. After import, use

    test-scenario get --with-case-detail

    again to confirm that steps are written and HTTP case/detail are expanded normally.
11. After importing API definition or test-case, check if params, headers, body, script variables are only schema sample values; use

    test-scenario update --file

    to supplement them when business values are needed.
12. When performing fine-grained editing, obtain the

    test-scenario-update

    schema and add or modify steps based on the complete structure.
13. After passing

    cli-schema validate

    , perform the update, then use

    test-scenario get --with-case-detail

    to confirm that

    steps

    are non-empty and the structure is correct.

test-scenario-update

• List data sources before creation: Environment variables, global variables, pre-step request/response, iterative data, script output.
• Prioritize using Apifox's native "read operation results of pre-steps" for data transfer between steps, such as

  {{$.1.response.body.token}}

  ,

  {{$.2.response.body.data.id}}

  ; it only takes effect in automated test scenarios and requires running the complete scenario, and cannot take values when running a single step alone.
• When the same data needs to be referenced multiple times, reused across modules, or you want a more stable name, use the extract variable in post-operations, then reference it with variables like

  {{token}}

  .
• Random suffixes, temporary identifiers, data generated across steps but not from responses are suitable for writing to environment variables, such as

  pm.environment.set('runSuffix', suffix);

  .
• When using pre-step results in scripts, do not directly write

  {{...}}

  ; use

  pm.variables.get("$.1.response.body.token")

  .
• Steps reference dependent step IDs/numbers; after inserting, deleting or rearranging steps, you must synchronously check whether

  {{$.stepNumber...}}

  still points to the correct step.
• Do not assume that the response path must be

  body.data.id

  ; confirm the path based on the real response first, such as

  {{$.2.response.body.id}}

  ,

  {{$.2.response.body.data.id}}

  ,

  {{$.2.response.body.data[0].id}}

  .
• When generating payloads, you must retain the

  {{...}}

  placeholders as they are; do not escape, split or rewrite them, otherwise they cannot be replaced during operation.
• When variables are empty, prioritize checking whether the complete scenario is run, step ID, JSONPath, response structure, step execution order and environment selection.
• These rules for inter-step transfer,

  {{$.stepNumber...}}

  and

  forEach

  only apply to

  test-scenario

  ; do not write them into single-interface

  test-case

  .

forEach.parameters.array

{
  "type": "forEach",
  "parameters": {
    "array": "{{$.1.response.body}}",
    "disableOnError": false
  }
}

{{$.2.element.id}}

{{$.7.response.body.data[0].id}}

• Interface Body:

  requestBody.data

  .
• Script Content:

  parameters.data

  .
• Pre/Post Scripts:

  preProcessors[*].data

  ,

  postProcessors[*].data

  .

• JSON Body should still be written as a string, not an object.
• Multi-line content is written with

  \n

  .
• Pre-formatting only affects the readability of client display and does not change execution semantics.
• Processors use a flat structure

  { id, type, data, defaultEnable, enable }

  instead of the old nested structure

  { type, config }

  .
• It is recommended to add a stable

  id

  to 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 scope, prioritize using

  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.
• Steps imported from API definition via

  import-steps

  may only have structure or schema sample values; you must read back and supplement params, headers, body, script variables, etc. according to the business scenario before running.

{
  "requestBody": {
    "type": "application/json",
    "data": "{\n  \"name\": \"Demo\",\n  \"description\": \"Readable in client\"\n}"
  },
  "postProcessors": [
    {
      "id": "postProcessors.0.customScript",
      "type": "customScript",
      "data": "pm.test('Return 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

• When referencing an interface to form an HTTP step, prioritize using the contract test/response verification built into the original interface; the default contract usually covers success status codes, such as 200.
• When interface contract testing is enabled, do not repeatedly add synonymous assertions such as "HTTP status code is 200"; only add business assertions beyond the contract.
• Only add

  assertion

  when there is no suitable contract verification or additional business fields need to be verified.
• Prioritize using visual

  assertion

  for regular checks such as HTTP status code, JSON field existence/equality, text inclusion, etc.; do not write

  customScript

  by default.
• Visual assertion fields use current schema enumerations: Use

  httpCode

  for HTTP status codes instead of

  responseCode

  ; use

  responseJson

  for JSON fields instead of

  responseBody

  ; use

  responseText

  +

  include

  for full-text inclusion; use

  equal

  for comparison operators instead of

  equals

  .

{
  "type": "assertion",
  "data": {
    "name": "Return ID",
    "subject": "responseJson",
    "comparison": "exists",
    "path": "$.data.id",
    "value": ""
  },
  "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 verification.
• Apifox script runtime uses the

  pm

  object to read/write variables, access responses and define assertions; 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);
});

• Pre-operations are suitable for authentication, data preparation, random value generation, database state initialization.
• Post-operations are suitable for cleaning up test data, undoing side effects, releasing resources.
• Scenarios with side effects must consider cleanup steps to avoid polluting the environment.
• High-risk operations such as database, external program, write-type interface steps require confirming that the environment is not a production environment before execution.

• Check the

  number

  for step order, do not only rely on the read-back array order.
• HTTP steps must carry correct interface binding information to avoid becoming isolated requests or abnormal client display. You can import interfaces using

  type: "http"

  +

  bindId: <endpointId>

  +

  bindType: "API"

  +

  syncMode: "SYNC_WITH_API"

  +

  httpApiCase.apiDetailId

  ; the backend will generate

  relatedId

  .
• Do not write the above complex binding structures manually for common endpoint/test-case/test-scenario imports; prioritize using

  test-scenario import-steps

  ; prioritize using

  test-scenario add-ref

  for referencing other scenarios.
• Complex business scenarios usually require

  syncMode: "MANUAL"

  to carry customized parameters, variable references and assertions; only binding APIs does not mean it is a usable business scenario.
• Container steps

  group/if/else/loop/forEach/onError

  must include

  disable=false

  ,

  parameters

  ,

  isOpen=true

  ,

  children=[]

  .
• Sub-steps are placed in

  children

  , not flattened.
• The display name of

  group

  is written in

  parameters.name

  , not the top-level

  name

  .

• if

  and conditional

  break

  use

  parameters.keyVariable

  +

  operator

  +

  valueVariable

  , do not write

  expression

  .

• parameters

  for

  else

  and

  onError

  should be empty objects

  {}

  .

• loop

  uses

  parameters.count

  , not

  times

  or other fields.

• delay

  uses

  parameters.timeout

  in milliseconds, not

  duration

  .

• script

  steps use

  parameters.type="customScript"

  ,

  parameters.data=<JS code>

  ,

  enable=true

  , do not write

  language/code

  .
• The URL field of

  customHttp

  is

  customHttpRequest.path

  , not

  url

  , and requires complete request fields.
• The

  testCaseRef

  field is

  relatedId

  , not

  caseId

  .

• relatedId

  is the HTTP case ID generated by the backend for scenario steps; do not copy and reuse it from old scenarios when creating new steps.

• test-scenario get --with-case-detail

  is used to confirm the step tree and internal configurations of HTTP case/detail, such as Body, Header, postProcessors; if the user explicitly requests verifiability, then perform operation verification and check the report.
• Currently,

  onError

  has the risk of unstable client expansion and configuration display even if CLI/schema/get is successful; when involving onError, you cannot judge availability solely based on successful validation/get, and need to confirm via the client.

• cli-schema validate

  only guarantees basic JSON structure, not that the runner, client or processor can definitely parse it correctly.
• After update or import, first use

  test-scenario get --with-case-detail

  to confirm that the step tree is non-empty and the structure is correct, but do not treat successful get as runnable.
• After creating, updating or importing steps, read back and confirm by default; do not run automatically; only execute

  test-scenario run

  and check the report when the user explicitly requests running, debugging failures or needs to verify runnability before delivery.
• When running fails, check the step details in the report to distinguish whether the failure occurs in the request, pre-script, post-script, assertion, variable reference or environment.
• Do not repeatedly overwrite the same business scenario when debugging complex scenarios; if necessary, create a versioned scenario to avoid mixing old steps and new structures.
• Temporarily deleting scripts/assertions can be used to locate problems, but do not treat "deleting functions" as the final fix.

1. Do not directly use the structure of

   test-case

   as the step structure of

   test-scenario

   ; prioritize using

   test-scenario import-steps --source test-case --endpoint <endpointId> --ids <caseIds>

   to import single-interface test cases into scenarios.
2. Do not only create an empty scenario name; it must contain a displayable and runnable step structure.
3. Do not mistakenly think that create can save steps; you must create metadata first, then use

   import-steps

   ,

   add-ref

   or

   update --file

   to write steps.
4. Do not guess complex step fields based on experience; read the schema and existing scenario templates first.
5. Do not let subsequent steps reference data from unconfirmed sources; first confirm that it comes from step responses, environment variables, iterative data, extractor or script output.
6. Do not execute steps with side effects without confirming the environment.
7. Before updating a scenario, you must first

   get --with-case-detail

   the original structure to avoid overwriting the entire step tree.
8. Do not repeatedly overwrite the same complex business scenario for debugging; if necessary, create a versioned scenario to avoid mixing old steps and new structures.