API Automation

WHartTest 接口自动化管理

先遵守这些

• 以当前代码为准：动作清单以 api_automation_tools.py 的 ACTIONS 为准；字段语义以 Django 的 models/serializers/views 为准。不要按旧 skill 或记忆猜字段。
• 先查后建：创建模块、环境、接口、用例、套件前，先 list_* / get_*，避免重复。
• 不要混用两个用例概念：
  • 单接口用例是 ApiInterfaceCase，接口路径是 api-interface-cases，CLI 动作用 *_interface_case。
  • 场景用例是 ApiTestCase，接口路径是 api-testcases，CLI 动作用 *_testcase。
• 同步只支持场景步骤：ApiSyncConfig.step 绑定的是 ApiTestCaseStep，不是 ApiInterfaceCaseStep。
• 复杂 JSON 用文件：--payload "@payload.json" 和 --params "@params.json" 都支持从文件读取 JSON。PowerShell 下必须给 @文件 加引号，否则会被当作 splatting 语法。
• 所有动作返回 JSON：成功通常是 {"status":"success","data":...}；失败是 {"status":"error",...}。

CLI 用法

python api_automation_tools.py --action <action_name> --project_id <project_id>
python api_automation_tools.py --action create_interface --project_id 1 --payload "@interface.json"
python api_automation_tools.py --action list_interfaces --project_id 1 --params '{"page":1,"page_size":50}'

可覆盖默认服务地址和 API Key：

python api_automation_tools.py --action list_modules --project_id 1 --base_url http://127.0.0.1:8000 --api_key wharttest-default-mcp-key-2025

用例概览

接口自动化测试中，用例管理分为两个页签，对应两种不同的用例类型：

工作流提示：先用 quick_debug_interface 或 run_interface 验证接口定义，再沉淀为接口用例或场景用例步骤。

真实概念边界

接口定义

ApiInterface 是保存的接口定义，支持 HTTP 和 SQL。先用 quick_debug_interface 或 run_interface 验证接口定义，再沉淀为单接口用例或场景用例步骤。

HTTP 的 headers、params 可以传对象或 key-value 数组，后端会规范化为数组。body.type 支持 none、form-data、x-www-form-urlencoded、raw、binary。

提取变量

extract 是变量名到 JMESPath 表达式的映射。extract_meta 是同名变量的元信息，支持 variable_type: "temporary" | "project" 和 source: "response" | "request"。

• 省略 source 时按 response 处理。
• source: "response" 从响应对象提取，继续使用现有写法，例如 body.data.token。
• source: "request" 从实际发出的请求快照提取，可用根字段是 method、url、headers、params、cookies、body、json、data，例如 method、url、headers.Authorization、body.username。
• source 只决定从请求还是响应提取；是否持久化到项目变量仍由 variable_type: "project" 决定。
• 接口定义的 serializer 只保留变量名同时存在于 extract 的 extract_meta 项。
• 同步配置的 extract 字段当前只同步提取表达式，不同步 extract_meta；如果改了请求/响应来源，要同步后手动检查场景步骤里的 extract_meta。

断言规则

validators 是断言规则数组，支持 {"eq": ["status_code", 200]} 和 {"check": "status_code", "expect": 200} 两种格式。check 默认按响应对象解析，可直接断言 status_code、headers、cookies、body。

断言没有独立的 source 或 validators_meta 字段。需要断言请求内容时，先用 extract + extract_meta.source: "request" 把请求字段提取成临时变量，再在同一步或后续步骤的 validators 里用 $变量名 断言。后端执行顺序是先提取、再断言。

接口定义执行器 InterfaceRunner 当前支持这些 comparator：eq、ne、lt、le、lte、gt、ge、gte、str_eq、contains、contained_by、type_match、regex_match、startswith、endswith、length_equal、length_greater_than、length_less_than、length_greater_or_equals、length_less_or_equals。

场景用例和单接口用例当前复用 TestCaseRunner，步骤断言实际映射的 comparator 是：eq、ne、lt、le、gt、ge、str_eq、contains、contained_by、type_match、regex_match。不要在场景步骤或单接口步骤里假设 lte、gte、startswith、endswith、length_* 会被执行，除非代码里的 api_testcases.runner.TestCaseRunner 已同步映射。

单接口用例（接口用例页签）

ApiInterfaceCase 用于"一个被测主接口"的测试。创建时顶层必须传 interface_id，后端会自动生成一个 role=main 的主步骤，主步骤绑定这个 interface_id 对应的接口。

steps_info 可选，用来补前置步骤；前置步骤 role 为 precondition。如果显式传 role=main，后端仍只保留一个主步骤，并按"前置步骤在前，主步骤最后"的顺序重建步骤。

单接口用例没有独立的批量执行接口。需要批量或混合执行时，把单接口用例加入任务套件的 interface_cases。

场景用例（场景用例页签）

ApiTestCase 是多步骤业务场景用例。创建或更新步骤使用 steps_info，新步骤需要 interface_id。每一步落库为 ApiTestCaseStep，可以覆盖 interface_data 中的请求、断言、提取、变量、hooks 等字段。

get_group_testcases 当前只返回分组下的场景用例；标签统计 get_tag_statistics 当前也只统计场景用例。

任务套件

ApiTestTaskSuite 可以同时包含场景用例和单接口用例：

• 创建/更新套件 payload 用 test_cases 表示场景用例 ID 列表。
• 创建/更新套件 payload 用 interface_cases 表示单接口用例 ID 列表。
• 向已有套件追加用例用 testcase_ids 和 interface_case_ids。
• 套件内用例类型是 case_type: "scenario" | "interface"。

常用枚举

• 数据库类型：mysql、postgresql、sqlite、oracle、sqlserver
• 环境变量类型：string、integer、float、boolean、json、list、dict
• 接口类型：http、sql
• HTTP 方法：GET、POST、PUT、DELETE、PATCH
• SQL 方法：fetchone、fetchmany、fetchall、insert、update、delete
• 提取变量类型：temporary、project
• 提取来源：response、request
• 用例/套件优先级：P0、P1、P2、P3
• 单接口步骤角色：precondition、main
• 任务套件用例类型：scenario、interface
• 执行状态：报告 success、failure、error；任务执行 pending、running、completed、failed、canceled；套件用例结果 pending、running、success、failure、error、skipped
• 同步字段：method、url、headers、params、body、setup_hooks、teardown_hooks、variables、validators、extract
• 同步模式：manual、auto

可用动作

基础资源

接口定义与调试

接口用例页签（单接口用例 ApiInterfaceCase）

查询参数说明：list_interface_cases 支持通过 --params 传入以下过滤参数：

• interface_id — 按接口 ID 过滤
• module_id — 按接口所属模块 ID 过滤（通过接口的 module 关联）
• no_module — 过滤未分类的接口用例（true / 1）

场景用例页签（场景用例 ApiTestCase）

标签与分组（两个页签共用）

标签和分组由接口用例和场景用例共用。get_group_testcases 只返回场景用例；接口用例的分组查询可通过 list_interface_cases 配合 --params '{"group_id": N}' 实现。

同步配置

任务套件

常见 Payload

移动模块

drop_position 取值：-1 表示移到目标模块前，1 表示移到目标模块后，0 表示移入目标模块。target_id 为 null 时只能移动到根层级，且 drop_position 不能为 0。

{"target_id": 10, "drop_position": 0}

创建数据库配置

数据库配置 serializer 暴露字段是 type，映射到模型字段 db_type。

{
  "name": "sqlite-dev",
  "type": "sqlite",
  "host": "local",
  "port": 0,
  "username": "tester",
  "password": "secret",
  "database": "/tmp/demo.sqlite3",
  "charset": "utf8mb4",
  "verify_ssl": false,
  "is_active": true
}

临时测试连接使用 db_type：

{"db_type": "sqlite", "database": "/tmp/demo.sqlite3"}

创建环境与变量

{
  "name": "dev",
  "base_url": "https://dev.example.com",
  "database_config": 8,
  "verify_ssl": false,
  "description": "开发环境"
}

{
  "environment_id": 10,
  "variables": [
    {"name": "token", "value": "demo-token", "type": "string"},
    {"name": "tenant_id", "value": "1001", "type": "integer"}
  ]
}

创建 HTTP 接口

{
  "name": "登录接口",
  "type": "http",
  "module": 5,
  "method": "POST",
  "url": "/api/login",
  "headers": {"Content-Type": "application/json"},
  "params": [],
  "body": {"type": "raw", "content": {"username": "admin", "password": "123456"}},
  "variables": {},
  "validators": [
    {"eq": ["status_code", 200]},
    {"eq": ["$login_request_method", "POST"]},
    {"contains": ["$login_request_method", "O"]},
    {"regex_match": ["$login_request_method", "^POST$"]},
    {"length_equal": ["$login_request_method", 4]}
  ],
  "extract": {
    "token": "body.data.token",
    "login_request_method": "method",
    "login_username": "body.username"
  },
  "extract_meta": {
    "token": {"variable_type": "project", "source": "response"},
    "login_request_method": {"variable_type": "temporary", "source": "request"},
    "login_username": {"variable_type": "temporary", "source": "request"}
  },
  "setup_hooks": [],
  "teardown_hooks": []
}

快速调试 SQL 接口

{
  "name": "查询用户",
  "type": "sql",
  "method": "fetchone",
  "sql": "select id, username from user where id = 1",
  "sql_params": {},
  "environment_id": 10
}

创建单接口用例（接口用例页签）

顶层 interface_id 是被测主接口。下面示例包含一个登录前置步骤；如果没有前置步骤，steps_info 可以省略或传空数组。

{
  "name": "查询个人资料",
  "description": "登录后调用个人资料接口",
  "priority": "P1",
  "group": 3,
  "tags": [1, 2],
  "interface_id": 20,
  "config": {},
  "steps_info": [
    {
      "name": "登录前置",
      "role": "precondition",
      "order": 1,
      "interface_id": 19,
      "interface_data": {
        "extract": {
          "token": "body.data.token",
          "login_request_method": "method"
        },
        "extract_meta": {
          "token": {"variable_type": "temporary", "source": "response"},
          "login_request_method": {"variable_type": "temporary", "source": "request"}
        },
        "validators": [
          {"eq": ["$login_request_method", "POST"]}
        ]
      }
    }
  ]
}

执行：

python api_automation_tools.py --action run_interface_case --project_id 1 --interface_case_id 88 --payload '{"environment_id":10}'

创建场景用例（场景用例页签）

create_testcase 用于多接口业务流程，不用于单接口用例。

{
  "name": "登录后查询个人资料",
  "description": "多接口业务流程",
  "priority": "P0",
  "group": 3,
  "tags": [1, 2],
  "config": {},
  "steps_info": [
    {
      "name": "调用登录接口",
      "order": 1,
      "interface_id": 19,
      "interface_data": {
        "extract": {
          "token": "body.data.token",
          "login_request_method": "method"
        },
        "extract_meta": {
          "token": {"variable_type": "temporary", "source": "response"},
          "login_request_method": {"variable_type": "temporary", "source": "request"}
        },
        "validators": [
          {"eq": ["status_code", 200]},
          {"eq": ["$login_request_method", "POST"]}
        ]
      }
    },
    {
      "name": "查询个人资料",
      "order": 2,
      "interface_id": 20,
      "interface_data": {
        "headers": [{"key": "Authorization", "value": "Bearer $token", "enabled": true}],
        "validators": [{"eq": ["status_code", 200]}]
      }
    }
  ]
}

创建和维护任务套件

{
  "name": "接口回归套件",
  "description": "混合执行场景用例与单接口用例",
  "priority": "P1",
  "fail_fast": false,
  "test_cases": [101, 102],
  "interface_cases": [201, 202]
}

追加用例：

python api_automation_tools.py --action add_suite_testcases --project_id 1 --task_suite_id 6 --payload '{"testcase_ids":[101],"interface_case_ids":[201]}'

移除用例：

python api_automation_tools.py --action remove_suite_testcase --project_id 1 --task_suite_id 6 --testcase_id 101
python api_automation_tools.py --action remove_suite_interface_case --project_id 1 --task_suite_id 6 --interface_case_id 201
python api_automation_tools.py --action remove_suite_case --project_id 1 --task_suite_id 6 --case_type interface --case_id 201

执行套件：

python api_automation_tools.py --action execute_task_suite --project_id 1 --payload '{"task_suite_id":6,"environment_id":10}'
python api_automation_tools.py --action get_task_case_results --project_id 1 --task_execution_id 88

创建同步配置

同步配置只用于场景用例步骤：

sync_fields 里填 extract 时只同步 interface.extract，当前后端 api_sync 没有同步 extract_meta；依赖 source: "request" 的提取规则同步后要检查步骤来源元信息。

{
  "name": "登录接口同步配置",
  "description": "保持场景步骤与接口定义一致",
  "interface": 20,
  "testcase": 101,
  "step": 301,
  "sync_fields": ["url", "headers", "body", "validators", "extract"],
  "sync_enabled": true,
  "sync_mode": "manual",
  "sync_trigger": {}
}

推荐工作流

按页签分步操作

1. 基础准备：get_module_tree、list_environments、list_interfaces，先确认基础资源。
2. 接口定义：新接口先 create_interface，再 quick_debug_interface 或 run_interface 验证。
3. 接口用例页签：用户要"单个接口测试"时，走接口用例页签 → 使用 create_interface_case（不是 create_testcase）。
4. 场景用例页签：用户要"业务流程/多接口编排/场景"时，走场景用例页签 → 使用 create_testcase。
5. 执行：单接口用例用 run_interface_case；场景用例用 run_testcase 或 batch_run_testcases。
6. 混合批量执行：创建任务套件，使用 test_cases + interface_cases 混合编排。
7. 同步：只有场景用例步骤需要接口定义同步时，才创建 ApiSyncConfig 并执行 sync_now / batch_sync。

快速判断

排查提示