Skip to content

ASSERTION_GUIDE.md

Latest commit

 

History

History
202 lines (157 loc) · 5.19 KB

ASSERTION_GUIDE.md

File metadata and controls

202 lines (157 loc) · 5.19 KB
Raw

API断言功能使用指南

功能概述

API断言功能允许您对API响应进行自动化验证，确保API返回的数据符合预期。每次API请求执行完成后，系统会自动执行配置的断言规则，并在日志中显示断言结果。

支持的断言类型

1. HTTP状态码断言 (HTTP_CODE)

  • 用途: 验证HTTP响应状态码
  • 期望值格式: 数字，如 200, 500, 404
  • 示例:
    • 期望状态码为200: 200
    • 期望状态码为500: 500

2. JSON包含关键字断言 (JSON_CONTAINS)

  • 用途: 检查响应体是否包含指定的关键字
  • 期望值格式: 字符串
  • 示例:
    • 检查成功响应: success
    • 检查错误信息: error
    • 检查特定字段: "status":"ok"

3. JSON路径断言 (JSON_PATH)

  • 用途: 使用JSONPath表达式检查响应体中的特定字段值
  • 期望值格式: JSONPath表达式
  • 示例:
    • 检查根字段: $.code
    • 检查嵌套字段: $.data.status
    • 检查数组元素: $.users[0].name
    • 检查消息字段: $.msg

配置方法

通过Web界面配置

  1. 编辑任务: 在任务管理页面，点击任务的"编辑"按钮
  2. 添加断言: 在任务编辑表单中，找到"断言配置"部分
  3. 配置断言规则:
    • 点击"添加断言"按钮
    • 选择断言类型
    • 输入期望值
    • 设置排序（可选）
  4. 保存任务: 保存任务时会同时保存断言配置

断言配置示例

示例1: 验证REST API成功响应

断言类型: HTTP_CODE
期望值: 200

断言类型: JSON_PATH
期望值: $.code

断言类型: JSON_CONTAINS
期望值: success

示例2: 验证错误响应

断言类型: HTTP_CODE
期望值: 400

断言类型: JSON_PATH
期望值: $.error

断言类型: JSON_CONTAINS
期望值: Invalid parameter

断言结果查看

在执行日志中查看

  1. 日志列表: 在执行日志页面，每个请求记录都会显示断言结果

  2. 断言状态:

    • ✅ 绿色: 所有断言通过
    • ❌ 红色: 存在断言失败
    • ⚪ 灰色: 无断言配置

  3. 断言摘要: 显示断言总数、通过数、失败数

查看详细断言结果

  1. 点击详情: 在日志记录中点击"详情"按钮
  2. 查看断言: 在详情页面点击"查看详细断言"按钮
  3. 断言详情: 显示每个断言的
    • 断言类型
    • 期望值
    • 实际值
    • 通过/失败状态
    • 错误信息（如果失败）

断言执行流程

  1. API请求执行: 系统执行API请求
  2. 获取响应: 获取HTTP状态码和响应体
  3. 执行断言: 根据配置的断言规则逐一验证
  4. 保存结果: 将断言结果保存到数据库
  5. 更新日志: 在API响应日志中更新断言结果

JSONPath语法参考

基本语法

  • $ - 根节点
  • . - 子节点操作符
  • .. - 递归下降
  • * - 通配符
  • [] - 数组索引

常用示例

{
  "code": 200,
  "msg": "success",
  "data": {
    "user": {
      "name": "张三",
      "age": 25
    },
    "items": [
      {"id": 1, "name": "商品1"},
      {"id": 2, "name": "商品2"}
    ]
  }
}

对应的JSONPath表达式:

  • $.code → 200
  • $.msg → "success"
  • $.data.user.name → "张三"
  • $.data.items[0].name → "商品1"
  • $.data.items[*].id → [1, 2]

最佳实践

1. 断言设计原则

  • 明确性: 断言应该有明确的通过/失败标准
  • 必要性: 只添加必要的断言，避免过度验证
  • 稳定性: 避免依赖可能变化的动态数据

2. 断言组合

  • 状态码 + 内容: 通常建议同时验证HTTP状态码和响应内容
  • 关键字 + 路径: 可以结合使用关键字和路径断言提高准确性

3. 错误处理

  • 预期失败: 对于可能失败的API，配置相应的失败断言
  • 错误信息: 使用JSON_CONTAINS验证特定的错误信息

4. 性能考虑

  • 断言数量: 避免添加过多断言影响执行性能
  • 复杂表达式: 简化JSONPath表达式提高执行效率

故障排除

常见问题

  1. JSON解析失败

    • 检查响应体是否为有效JSON格式
    • 确认Content-Type是否正确

  2. JSON路径不存在

    • 验证JSONPath表达式语法
    • 检查响应数据结构是否发生变化

  3. 断言不执行

    • 确认任务是否配置了断言
    • 检查任务是否正常执行

调试技巧

  1. 查看响应体: 在日志详情中查看完整的响应体
  2. 测试JSONPath: 使用在线JSONPath测试工具验证表达式
  3. 简化断言: 从简单的断言开始，逐步增加复杂性

数据库表结构

api_assertion表

  • id: 断言ID
  • task_id: 关联的任务ID
  • response_id: 关联的响应ID（执行结果）
  • assertion_type: 断言类型
  • expected_value: 期望值
  • actual_value: 实际值
  • passed: 是否通过
  • error_message: 错误信息
  • sort_order: 排序顺序

api_response表新增字段

  • assertion_result: 断言结果汇总
  • all_assertions_passed: 所有断言是否通过

更新日志

v1.0.0

  • 新增HTTP状态码断言
  • 新增JSON包含关键字断言
  • 新增JSON路径断言
  • 支持断言结果查看和详情展示
  • 集成到任务执行流程中