api-automation

name	api-automation
description	WHartTest 接口自动化管理工具。用于按真实后端接口管理接口模块、数据库配置、环境与变量、自定义函数、接口定义与调试、单接口用例 ApiInterfaceCase、场景用例 ApiTestCase、任务套件、执行报告与同步配置。当需要创建、查询、修改、执行 API 自动化资源，区分单接口测试和场景用例，或排查执行、同步、任务套件问题时使用。

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

用例概览

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

维度	单接口用例（接口用例页签）	场景用例（场景用例页签）
模型	ApiInterfaceCase	ApiTestCase
API 路径	api-interface-cases	api-testcases
CLI 动作前缀	*_interface_case	*_testcase
用途	针对单个接口进行测试，比如验证登录接口的各种入参组合	编排多接口业务流程，比如"登录→查询个人资料→修改资料"
步骤结构	一个 role=main 的主步骤（绑定被测接口）+ 可选 role=precondition 的前置步骤	多个 role 无区别的步骤，每步绑定一个接口，按 order 顺序执行
主接口绑定	创建时顶层传 interface_id，后端自动生成主步骤	无顶层绑定，每步各自指定 interface_id
批量执行	通过任务套件（task_suite.interface_cases）	通过 batch_run_testcases 或任务套件（task_suite.test_cases）
报告模型	ApiInterfaceCaseReport	ApiTestReport
同步配置	不支持	支持（ApiSyncConfig 绑定场景步骤）

工作流提示：先用 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

可用动作

基础资源

Action	说明
list_modules / get_module / create_module / update_module / delete_module	接口模块 CRUD
get_module_tree / search_modules / move_module	模块树、搜索与移动
list_database_configs / get_database_config / create_database_config / update_database_config / delete_database_config	数据库配置 CRUD
test_database_connection / test_saved_database_connection	测试临时或已保存数据库连接
list_environments / get_environment / create_environment / update_environment / delete_environment	环境 CRUD
clone_environment	克隆环境及变量
list_environment_variables / get_environment_variable / create_environment_variable / update_environment_variable / delete_environment_variable	环境变量 CRUD
batch_create_environment_variables / batch_update_environment_variables	批量维护环境变量
list_global_headers / get_global_header / create_global_header / update_global_header / delete_global_header	全局请求头 CRUD
list_functions / get_function / create_function / update_function / delete_function	自定义函数 CRUD
generate_debugtalk / execute_function	生成 debugtalk 或试运行函数代码

接口定义与调试

Action	说明
list_interfaces / get_interface / create_interface / update_interface / delete_interface	接口定义 CRUD
duplicate_interface	复制接口定义
quick_debug_interface	不落库快速调试接口
run_interface	执行已保存接口
list_interface_results / get_interface_result	查询接口调试/执行结果

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

Action	说明
list_interface_cases / get_interface_case / create_interface_case / update_interface_case / delete_interface_case	单接口用例 CRUD
copy_interface_case	复制单接口用例
run_interface_case	执行单接口用例
get_interface_case_history_reports	查看某个单接口用例历史报告
list_interface_case_reports / get_interface_case_report	查询单接口用例报告

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

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

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

Action	说明
list_testcases / get_testcase / create_testcase / update_testcase / delete_testcase	场景用例 CRUD
get_available_interfaces	获取可引用接口列表
get_referenced_interfaces	查看场景用例引用的接口
copy_testcase	复制场景用例
run_testcase	执行单个场景用例
batch_run_testcases	批量执行场景用例
update_testcase_step / delete_testcase_step / reorder_testcase_steps	维护场景用例步骤
get_history_reports	查看某个场景用例历史报告
list_test_reports / get_test_report	查询场景用例报告

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

Action	说明
list_testcase_tags / get_testcase_tag / create_testcase_tag / update_testcase_tag / delete_testcase_tag	用例标签 CRUD
get_tag_statistics	标签使用统计（当前统计场景用例）
list_testcase_groups / get_testcase_group / create_testcase_group / update_testcase_group / delete_testcase_group	用例分组 CRUD
get_testcase_group_tree	分组树
get_group_testcases	某分组下的场景用例

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

同步配置

Action	说明
list_sync_configs / get_sync_config / create_sync_config / update_sync_config / delete_sync_config	场景步骤同步配置 CRUD
sync_now / batch_sync	立即同步或批量同步
list_sync_histories / get_sync_history / rollback_sync_history	同步历史与回滚
list_global_sync_configs / get_global_sync_config / create_global_sync_config / update_global_sync_config / delete_global_sync_config	全局同步配置 CRUD
set_active_global_sync_config / get_current_global_sync_config	设置或读取当前生效全局同步配置

任务套件

Action	说明
list_task_suites / get_task_suite / create_task_suite / update_task_suite / delete_task_suite	任务套件 CRUD
add_suite_testcases	向套件追加场景用例和/或单接口用例
remove_suite_testcase	从套件移除场景用例，兼容旧路径
remove_suite_interface_case	从套件移除单接口用例
remove_suite_case	按 case_type + case_id 从套件移除任意类型用例
list_task_executions / get_task_execution	查询任务执行
execute_task_suite	发起套件执行
get_task_case_results	查看某次套件执行的每条用例结果
cancel_task_execution	取消待执行/执行中的任务

常见 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" 
      
      
      
      
      
  
   
     
     
     
  
   
        
        
        
  
   
   

快速调试 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": 
           
           
        
         
              
              
        
         
            
        
      
    
  

执行：

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"
        
         
              
              
        
         
            
            
        
      
    
    
       
       
       
       
              
           
      
    
  

创建和维护任务套件

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

快速判断

用户说的是	对应的页签	创建动作	执行动作
"测试登录接口"、"单个接口验证"	接口用例页签	create_interface_case	run_interface_case
"登录后查询资料"、"业务流程"	场景用例页签	create_testcase	run_testcase / batch_run_testcases
"批量执行回归"	任务套件	create_task_suite	execute_task_suite

排查提示

问题	处理建议
401 Unauthorized / 403 Forbidden	检查 --api_key 与项目权限
404 Not Found	检查 project_id 和资源 ID 是否属于同一项目
JSON 解析失败	使用合法 JSON，复杂结构改用 "@文件.json"；PowerShell 下不要省略引号
创建单接口用例失败	确认顶层 interface_id 存在且属于当前项目
单接口用例没有主步骤	后端应自动创建 role=main；检查创建响应中的 main_step
场景步骤创建失败	新步骤必须提供有效 interface_id，或更新已有步骤时提供 step_id
套件用例类型不对	场景用例放 test_cases/testcase_ids，单接口用例放 interface_cases/interface_case_ids
同步配置不生效	确认目标是 ApiTestCaseStep；单接口用例步骤当前不支持同步配置