Neura Market
Back to .md Directory
TEST_CASES.md

Aegra API 测试用例集

> 基于 Aegra Agent Protocol Server 的完整 API 测试案例集

zylhub
May 2, 2026
0 downloads
0 views
agent
View source

Aegra API 测试用例集

基于 Aegra Agent Protocol Server 的完整 API 测试案例集 测试环境: http://localhost:8000 测试用户: test_user@example.com 认证方式: Bearer Token

目录

  1. 测试环境准备
  2. Health 模块测试
  3. Assistants 模块测试
  4. Threads 模块测试
  5. Runs 模块测试
  6. Store 模块测试
  7. 异常场景测试

测试环境准备

环境变量配置

export API_BASE_URL="http://localhost:8000"
export API_TOKEN="your_bearer_token_here"
export ASSISTANT_ID=""
export THREAD_ID=""
export RUN_ID=""

通用 curl 选项

# 通用请求头
COMMON_HEADERS=(
  -H "Authorization: Bearer $API_TOKEN"
  -H "Content-Type: application/json"
)

Health 模块测试

测试组 1: 健康检查端点

TC-H-001: GET /health - 服务健康检查

测试目的: 验证服务基本健康状态

测试类型: 正向测试

curl 命令:

curl -X GET "$API_BASE_URL/health" \
  -H "Authorization: Bearer $API_TOKEN" \
  -w "\nHTTP Status: %{http_code}\n"

预期响应:

{
  "status": "healthy"
}

预期状态码: 200

验证点:

  • HTTP 状态码为 200
  • 响应体包含 status 字段
  • status 值为 "healthy"

TC-H-002: GET /ready - 就绪状态检查

测试目的: 验证服务已就绪并可接受请求

测试类型: 正向测试

curl 命令:

curl -X GET "$API_BASE_URL/ready" \
  -H "Authorization: Bearer $API_TOKEN" \
  -w "\nHTTP Status: %{http_code}\n"

预期响应:

{
  "status": "ready"
}

预期状态码: 200

验证点:

  • HTTP 状态码为 200
  • 响应体包含 status 字段
  • status 值为 "ready"

TC-H-003: GET /live - 存活状态检查

测试目的: 验证服务进程正在运行

测试类型: 正向测试

curl 命令:

curl -X GET "$API_BASE_URL/live" \
  -H "Authorization: Bearer $API_TOKEN" \
  -w "\nHTTP Status: %{http_code}\n"

预期响应:

{
  "status": "live"
}

预期状态码: 200

验证点:

  • HTTP 状态码为 200
  • 响应体包含 status 字段
  • status 值为 "live"

TC-H-004: GET /info - 服务信息查询

测试目的: 获取服务版本和配置信息

测试类型: 正向测试

curl 命令:

curl -X GET "$API_BASE_URL/info" \
  -H "Authorization: Bearer $API_TOKEN" \
  -w "\nHTTP Status: %{http_code}\n"

预期响应:

{
  "version": "0.1.0",
  "project_name": "Aegra",
  "features": []
}

预期状态码: 200

验证点:

  • HTTP 状态码为 200
  • 响应体包含 version 字段
  • 响应体包含 project_name 字段
  • project_name 值为 "Aegra"

TC-H-005: GET / - 根端点

测试目的: 验证根端点返回服务基本信息

测试类型: 正向测试

curl 命令:

curl -X GET "$API_BASE_URL/" \
  -H "Authorization: Bearer $API_TOKEN" \
  -w "\nHTTP Status: %{http_code}\n"

预期响应:

{
  "message": "Aegra",
  "version": "0.1.0",
  "status": "running"
}

预期状态码: 200

验证点:

  • HTTP 状态码为 200
  • 响应体包含 message、version、status 字段
  • status 值为 "running"

Assistants 模块测试

测试组 2: Assistants CRUD 操作

TC-A-001: POST /assistants - 创建 Assistant (正向测试)

测试目的: 成功创建一个新的 Assistant

测试类型: 正向测试

前置条件: 无

curl 命令:

curl -X POST "$API_BASE_URL/assistants" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "assistant_id": "test-assistant-001",
    "name": "测试助手",
    "description": "这是一个测试用的助手",
    "graph_id": "agent",
    "config": {
      "model": "gpt-4",
      "temperature": 0.7
    },
    "metadata": {
      "version": "1.0",
      "created_by": "test"
    }
  }' \
  -w "\nHTTP Status: %{http_code}\n"

预期响应:

{
  "assistant_id": "test-assistant-001",
  "name": "测试助手",
  "description": "这是一个测试用的助手",
  "graph_id": "agent",
  "config": {
    "model": "gpt-4",
    "temperature": 0.7
  },
  "metadata": {
    "version": "1.0",
    "created_by": "test",
    "owner": "test_user@example.com"
  },
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-01T00:00:00Z"
}

预期状态码: 201

验证点:

  • HTTP 状态码为 201
  • 响应体包含 assistant_id 字段
  • assistant_id 与请求中的值一致
  • 响应体包含 created_at 和 updated_at 时间戳
  • metadata 中自动添加了 owner 字段

依赖设置: 保存返回的 assistant_id 到环境变量 ASSISTANT_ID

TC-A-002: POST /assistants - 创建 Assistant (重复 ID)

测试目的: 验证创建重复 ID 的 Assistant 时返回错误

测试类型: 异常测试

前置条件: TC-A-001 已执行

curl 命令:

curl -X POST "$API_BASE_URL/assistants" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "assistant_id": "test-assistant-001",
    "name": "重复助手",
    "description": "这是一个重复的助手",
    "graph_id": "agent"
  }' \
  -w "\nHTTP Status: %{http_code}\n"

预期响应:

{
  "error": "conflict",
  "message": "Assistant 'test-assistant-001' already exists"
}

预期状态码: 409

验证点:

  • HTTP 状态码为 409
  • 响应体包含 error 字段，值为 "conflict"
  • 响应体包含 message 字段说明冲突原因

TC-A-003: POST /assistants - 创建 Assistant (缺少必需字段)

测试目的: 验证缺少必需字段时的验证错误

测试类型: 异常测试

前置条件: 无

curl 命令:

curl -X POST "$API_BASE_URL/assistants" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "不完整助手"
  }' \
  -w "\nHTTP Status: %{http_code}\n"

预期响应:

{
  "error": "validation_error",
  "message": "Validation failed",
  "details": {
    "field": "graph_id",
    "reason": "field required"
  }
}

预期状态码: 422

验证点:

  • HTTP 状态码为 422
  • 响应体包含 error 字段
  • 响应体包含 details 字段说明验证错误

TC-A-004: GET /assistants - 列出所有 Assistants

测试目的: 获取当前用户的所有 Assistants

测试类型: 正向测试

前置条件: TC-A-001 已执行

curl 命令:

curl -X GET "$API_BASE_URL/assistants" \
  -H "Authorization: Bearer $API_TOKEN" \
  -w "\nHTTP Status: %{http_code}\n"

预期响应:

{
  "assistants": [
    {
      "assistant_id": "test-assistant-001",
      "name": "测试助手",
      "description": "这是一个测试用的助手",
      "graph_id": "agent",
      "created_at": "2024-01-01T00:00:00Z",
      "updated_at": "2024-01-01T00:00:00Z"
    }
  ],
  "total": 1
}

预期状态码: 200

验证点:

  • HTTP 状态码为 200
  • 响应体包含 assistants 数组
  • 响应体包含 total 字段表示总数
  • 数组中包含 TC-A-001 创建的 Assistant

TC-A-005: GET /assistants/{assistant_id} - 获取指定 Assistant

测试目的: 根据 ID 获取单个 Assistant 详情

测试类型: 正向测试

前置条件: TC-A-001 已执行，ASSISTANT_ID 已设置

curl 命令:

curl -X GET "$API_BASE_URL/assistants/$ASSISTANT_ID" \
  -H "Authorization: Bearer $API_TOKEN" \
  -w "\nHTTP Status: %{http_code}\n"

预期响应:

{
  "assistant_id": "test-assistant-001",
  "name": "测试助手",
  "description": "这是一个测试用的助手",
  "graph_id": "agent",
  "config": {
    "model": "gpt-4",
    "temperature": 0.7
  },
  "metadata": {
    "version": "1.0",
    "created_by": "test",
    "owner": "test_user@example.com"
  },
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-01T00:00:00Z"
}

预期状态码: 200

验证点:

  • HTTP 状态码为 200
  • 响应体包含完整的 Assistant 信息
  • assistant_id 与请求路径中的 ID 一致

TC-A-006: GET /assistants/{assistant_id} - 获取不存在的 Assistant

测试目的: 验证查询不存在的 Assistant 时返回 404

测试类型: 异常测试

前置条件: 无

curl 命令:

curl -X GET "$API_BASE_URL/assistants/non-existent-id" \
  -H "Authorization: Bearer $API_TOKEN" \
  -w "\nHTTP Status: %{http_code}\n"

预期响应:

{
  "error": "not_found",
  "message": "Assistant 'non-existent-id' not found"
}

预期状态码: 404

验证点:

  • HTTP 状态码为 404
  • 响应体包含 error 字段，值为 "not_found"

TC-A-007: PATCH /assistants/{assistant_id} - 更新 Assistant

测试目的: 更新 Assistant 的部分字段

测试类型: 正向测试

前置条件: TC-A-001 已执行，ASSISTANT_ID 已设置

curl 命令:

curl -X PATCH "$API_BASE_URL/assistants/$ASSISTANT_ID" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "测试助手(已更新)",
    "description": "更新后的描述",
    "config": {
      "temperature": 0.8
    }
  }' \
  -w "\nHTTP Status: %{http_code}\n"

预期响应:

{
  "assistant_id": "test-assistant-001",
  "name": "测试助手(已更新)",
  "description": "更新后的描述",
  "graph_id": "agent",
  "config": {
    "model": "gpt-4",
    "temperature": 0.8
  },
  "metadata": {
    "version": "1.0",
    "created_by": "test",
    "owner": "test_user@example.com"
  },
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-01T01:00:00Z"
}

预期状态码: 200

验证点:

  • HTTP 状态码为 200
  • name 字段已更新
  • description 字段已更新
  • config.temperature 已更新为 0.8
  • updated_at 时间戳已更新
  • created_at 保持不变

TC-A-008: PATCH /assistants/{assistant_id} - 更新不存在的 Assistant

测试目的: 验证更新不存在的 Assistant 时返回 404

测试类型: 异常测试

前置条件: 无

curl 命令:

curl -X PATCH "$API_BASE_URL/assistants/non-existent-id" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "更新不存在的助手"
  }' \
  -w "\nHTTP Status: %{http_code}\n"

预期响应:

{
  "error": "not_found",
  "message": "Assistant 'non-existent-id' not found"
}

预期状态码: 404

验证点:

  • HTTP 状态码为 404
  • 响应体包含 error 字段

TC-A-009: POST /assistants/search - 搜索 Assistants

测试目的: 根据条件搜索 Assistants

测试类型: 正向测试

前置条件: TC-A-001 已执行

curl 命令:

curl -X POST "$API_BASE_URL/assistants/search" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "graph_id": "agent",
    "limit": 10,
    "offset": 0
  }' \
  -w "\nHTTP Status: %{http_code}\n"

预期响应:

[
  {
    "assistant_id": "test-assistant-001",
    "name": "测试助手(已更新)",
    "graph_id": "agent",
    "created_at": "2024-01-01T00:00:00Z",
    "updated_at": "2024-01-01T01:00:00Z"
  }
]

预期状态码: 200

验证点:

  • HTTP 状态码为 200
  • 响应体为数组
  • 返回的 Assistant 匹配搜索条件
  • graph_id 为 "agent"

TC-A-010: POST /assistants/count - 统计 Assistants 数量

测试目的: 统计符合条件的 Assistants 数量

测试类型: 正向测试

前置条件: TC-A-001 已执行

curl 命令:

curl -X POST "$API_BASE_URL/assistants/count" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "graph_id": "agent"
  }' \
  -w "\nHTTP Status: %{http_code}\n"

预期响应:

1

预期状态码: 200

验证点:

  • HTTP 状态码为 200
  • 响应体为整数
  • 返回值大于等于 1

TC-A-011: GET /assistants/{assistant_id}/schemas - 获取 Assistant Schema

测试目的: 获取 Assistant 的输入、输出、状态等 Schema 定义

测试类型: 正向测试

前置条件: TC-A-001 已执行，ASSISTANT_ID 已设置

curl 命令:

curl -X GET "$API_BASE_URL/assistants/$ASSISTANT_ID/schemas" \
  -H "Authorization: Bearer $API_TOKEN" \
  -w "\nHTTP Status: %{http_code}\n"

预期响应:

{
  "input_schema": {
    "type": "object",
    "properties": {
      "messages": {
        "type": "array",
        "items": {
          "type": "object"
        }
      }
    }
  },
  "output_schema": {
    "type": "object"
  },
  "state_schema": {
    "type": "object"
  },
  "config_schema": {
    "type": "object"
  },
  "context_schema": {
    "type": "object"
  }
}

预期状态码: 200

验证点:

  • HTTP 状态码为 200
  • 响应体包含 input_schema 字段
  • 响应体包含 output_schema 字段
  • 响应体包含 state_schema 字段
  • 响应体包含 config_schema 字段
  • 响应体包含 context_schema 字段

TC-A-012: GET /assistants/{assistant_id}/graph - 获取图结构

测试目的: 获取 Assistant 的图结构用于可视化

测试类型: 正向测试

前置条件: TC-A-001 已执行，ASSISTANT_ID 已设置

curl 命令:

curl -X GET "$API_BASE_URL/assistants/$ASSISTANT_ID/graph" \
  -H "Authorization: Bearer $API_TOKEN" \
  -w "\nHTTP Status: %{http_code}\n"

预期响应:

{
  "nodes": [
    {
      "id": "agent",
      "type": "node"
    }
  ],
  "edges": []
}

预期状态码: 200

验证点:

  • HTTP 状态码为 200
  • 响应体包含 nodes 数组
  • 响应体包含 edges 数组

TC-A-013: GET /assistants/{assistant_id}/graph - 获取图结构 (xray 模式)

测试目的: 获取 Assistant 的详细图结构 (xray 模式)

测试类型: 正向测试

前置条件: TC-A-001 已执行，ASSISTANT_ID 已设置

curl 命令:

curl -X GET "$API_BASE_URL/assistants/$ASSISTANT_ID/graph?xray=1" \
  -H "Authorization: Bearer $API_TOKEN" \
  -w "\nHTTP Status: %{http_code}\n"

预期响应:

{
  "nodes": [
    {
      "id": "agent",
      "type": "node",
      "data": {}
    }
  ],
  "edges": []
}

预期状态码: 200

验证点:

  • HTTP 状态码为 200
  • 响应体包含详细的节点信息

TC-A-014: GET /assistants/{assistant_id}/subgraphs - 获取子图

测试目的: 获取 Assistant 的子图列表

测试类型: 正向测试

前置条件: TC-A-001 已执行，ASSISTANT_ID 已设置

curl 命令:

curl -X GET "$API_BASE_URL/assistants/$ASSISTANT_ID/subgraphs" \
  -H "Authorization: Bearer $API_TOKEN" \
  -w "\nHTTP Status: %{http_code}\n"

预期响应:

[]

预期状态码: 200

验证点:

  • HTTP 状态码为 200
  • 响应体为数组

TC-A-015: POST /assistants/{assistant_id}/versions - 列出版本

测试目的: 获取 Assistant 的所有版本

测试类型: 正向测试

前置条件: TC-A-001 已执行，ASSISTANT_ID 已设置

curl 命令:

curl -X POST "$API_BASE_URL/assistants/$ASSISTANT_ID/versions" \
  -H "Authorization: Bearer $API_TOKEN" \
  -w "\nHTTP Status: %{http_code}\n"

预期响应:

[
  {
    "assistant_id": "test-assistant-001",
    "version": 1,
    "name": "测试助手(已更新)",
    "created_at": "2024-01-01T01:00:00Z"
  }
]

预期状态码: 200

验证点:

  • HTTP 状态码为 200
  • 响应体为数组
  • 每个版本包含 version 字段

TC-A-016: POST /assistants/{assistant_id}/latest - 设置最新版本

测试目的: 将指定版本设置为最新版本

测试类型: 正向测试

前置条件: TC-A-001 已执行，ASSISTANT_ID 已设置

curl 命令:

curl -X POST "$API_BASE_URL/assistants/$ASSISTANT_ID/latest" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "version": 1
  }' \
  -w "\nHTTP Status: %{http_code}\n"

预期响应:

{
  "assistant_id": "test-assistant-001",
  "version": 1,
  "name": "测试助手(已更新)",
  "is_latest": true
}

预期状态码: 200

验证点:

  • HTTP 状态码为 200
  • is_latest 字段为 true

TC-A-017: DELETE /assistants/{assistant_id} - 删除 Assistant

测试目的: 删除指定的 Assistant

测试类型: 正向测试

前置条件: TC-A-001 已执行，ASSISTANT_ID 已设置

curl 命令:

curl -X DELETE "$API_BASE_URL/assistants/$ASSISTANT_ID" \
  -H "Authorization: Bearer $API_TOKEN" \
  -w "\nHTTP Status: %{http_code}\n"

预期响应:

{
  "status": "deleted"
}

预期状态码: 200

验证点:

  • HTTP 状态码为 200
  • 响应体包含 status 字段，值为 "deleted"

TC-A-018: DELETE /assistants/{assistant_id} - 删除不存在的 Assistant

测试目的: 验证删除不存在的 Assistant 时返回 404

测试类型: 异常测试

前置条件: 无

curl 命令:

curl -X DELETE "$API_BASE_URL/assistants/non-existent-id" \
  -H "Authorization: Bearer $API_TOKEN" \
  -w "\nHTTP Status: %{http_code}\n"

预期响应:

{
  "error": "not_found",
  "message": "Assistant 'non-existent-id' not found"
}

预期状态码: 404

验证点:

  • HTTP 状态码为 404
  • 响应体包含 error 字段

Threads 模块测试

测试组 3: Threads CRUD 操作

TC-T-001: POST /threads - 创建 Thread (正向测试)

测试目的: 成功创建一个新的 Thread

测试类型: 正向测试

前置条件: 无

curl 命令:

curl -X POST "$API_BASE_URL/threads" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "thread_id": "test-thread-001",
    "metadata": {
      "title": "测试对话",
      "description": "这是一个测试对话线程"
    }
  }' \
  -w "\nHTTP Status: %{http_code}\n"

预期响应:

{
  "thread_id": "test-thread-001",
  "status": "idle",
  "metadata": {
    "title": "测试对话",
    "description": "这是一个测试对话线程",
    "owner": "test_user@example.com",
    "assistant_id": null,
    "graph_id": null,
    "thread_name": ""
  },
  "user_id": "test_user@example.com",
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-01T00:00:00Z"
}

预期状态码: 201

验证点:

  • HTTP 状态码为 201
  • 响应体包含 thread_id 字段
  • status 默认为 "idle"
  • metadata 中自动添加了 owner 字段

依赖设置: 保存返回的 thread_id 到环境变量 THREAD_ID

TC-T-002: POST /threads - 创建 Thread (自动生成 ID)

测试目的: 验证不指定 thread_id 时自动生成

测试类型: 正向测试

前置条件: 无

curl 命令:

curl -X POST "$API_BASE_URL/threads" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "metadata": {
      "title": "自动生成ID的线程"
    }
  }' \
  -w "\nHTTP Status: %{http_code}\n"

预期响应:

{
  "thread_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "idle",
  "metadata": {
    "title": "自动生成ID的线程",
    "owner": "test_user@example.com",
    "assistant_id": null,
    "graph_id": null,
    "thread_name": ""
  },
  "user_id": "test_user@example.com",
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-01T00:00:00Z"
}

预期状态码: 201

验证点:

  • HTTP 状态码为 201
  • thread_id 为 UUID 格式
  • status 为 "idle"

TC-T-003: POST /threads - 创建 Thread (重复 ID，if_exists=do_nothing)

测试目的: 验证 if_exists=do_nothing 时返回现有 Thread

测试类型: 正向测试

前置条件: TC-T-001 已执行

curl 命令:

curl -X POST "$API_BASE_URL/threads" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "thread_id": "test-thread-001",
    "if_exists": "do_nothing",
    "metadata": {
      "title": "重复的线程"
    }
  }' \
  -w "\nHTTP Status: %{http_code}\n"

预期响应:

{
  "thread_id": "test-thread-001",
  "status": "idle",
  "metadata": {
    "title": "测试对话",
    "description": "这是一个测试对话线程",
    "owner": "test_user@example.com",
    "assistant_id": null,
    "graph_id": null,
    "thread_name": ""
  },
  "user_id": "test_user@example.com",
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-01T00:00:00Z"
}

预期状态码: 200

验证点:

  • HTTP 状态码为 200
  • 返回的是已存在的 Thread
  • metadata 保持原值，未被更新

TC-T-004: POST /threads - 创建 Thread (重复 ID，默认行为)

测试目的: 验证重复 ID 时返回 409 错误

测试类型: 异常测试

前置条件: TC-T-001 已执行

curl 命令:

curl -X POST "$API_BASE_URL/threads" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "thread_id": "test-thread-001",
    "metadata": {
      "title": "重复的线程"
    }
  }' \
  -w "\nHTTP Status: %{http_code}\n"

预期响应:

{
  "error": "conflict",
  "message": "Thread 'test-thread-001' already exists"
}

预期状态码: 409

验证点:

  • HTTP 状态码为 409
  • 响应体包含 error 字段

TC-T-005: GET /threads - 列出所有 Threads

测试目的: 获取当前用户的所有 Threads

测试类型: 正向测试

前置条件: TC-T-001 已执行

curl 命令:

curl -X GET "$API_BASE_URL/threads" \
  -H "Authorization: Bearer $API_TOKEN" \
  -w "\nHTTP Status: %{http_code}\n"

预期响应:

{
  "threads": [
    {
      "thread_id": "test-thread-001",
      "status": "idle",
      "metadata": {
        "title": "测试对话",
        "owner": "test_user@example.com"
      },
      "created_at": "2024-01-01T00:00:00Z",
      "updated_at": "2024-01-01T00:00:00Z"
    }
  ],
  "total": 1
}

预期状态码: 200

验证点:

  • HTTP 状态码为 200
  • 响应体包含 threads 数组
  • 响应体包含 total 字段
  • 数组中包含 TC-T-001 创建的 Thread

TC-T-006: GET /threads/{thread_id} - 获取指定 Thread

测试目的: 根据 ID 获取单个 Thread 详情

测试类型: 正向测试

前置条件: TC-T-001 已执行，THREAD_ID 已设置

curl 命令:

curl -X GET "$API_BASE_URL/threads/$THREAD_ID" \
  -H "Authorization: Bearer $API_TOKEN" \
  -w "\nHTTP Status: %{http_code}\n"

预期响应:

{
  "thread_id": "test-thread-001",
  "status": "idle",
  "metadata": {
    "title": "测试对话",
    "description": "这是一个测试对话线程",
    "owner": "test_user@example.com",
    "assistant_id": null,
    "graph_id": null,
    "thread_name": ""
  },
  "user_id": "test_user@example.com",
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-01T00:00:00Z"
}

预期状态码: 200

验证点:

  • HTTP 状态码为 200
  • thread_id 与请求路径中的 ID 一致

TC-T-007: GET /threads/{thread_id} - 获取不存在的 Thread

测试目的: 验证查询不存在的 Thread 时返回 404

测试类型: 异常测试

前置条件: 无

curl 命令:

curl -X GET "$API_BASE_URL/threads/non-existent-thread" \
  -H "Authorization: Bearer $API_TOKEN" \
  -w "\nHTTP Status: %{http_code}\n"

预期响应:

{
  "error": "not_found",
  "message": "Thread 'non-existent-thread' not found"
}

预期状态码: 404

验证点:

  • HTTP 状态码为 404
  • 响应体包含 error 字段

TC-T-008: PATCH /threads/{thread_id} - 更新 Thread

测试目的: 更新 Thread 的 metadata

测试类型: 正向测试

前置条件: TC-T-001 已执行，THREAD_ID 已设置

curl 命令:

curl -X PATCH "$API_BASE_URL/threads/$THREAD_ID" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "metadata": {
      "title": "测试对话(已更新)",
      "new_field": "新字段值"
    }
  }' \
  -w "\nHTTP Status: %{http_code}\n"

预期响应:

{
  "thread_id": "test-thread-001",
  "status": "idle",
  "metadata": {
    "title": "测试对话(已更新)",
    "description": "这是一个测试对话线程",
    "owner": "test_user@example.com",
    "assistant_id": null,
    "graph_id": null,
    "thread_name": "",
    "new_field": "新字段值"
  },
  "user_id": "test_user@example.com",
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-01T01:00:00Z"
}

预期状态码: 200

验证点:

  • HTTP 状态码为 200
  • title 字段已更新
  • 新增了 new_field 字段
  • updated_at 时间戳已更新
  • created_at 保持不变

TC-T-009: PATCH /threads/{thread_id} - 更新不存在的 Thread

测试目的: 验证更新不存在的 Thread 时返回 404

测试类型: 异常测试

前置条件: 无

curl 命令:

curl -X PATCH "$API_BASE_URL/threads/non-existent-thread" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "metadata": {
      "title": "更新不存在的线程"
    }
  }' \
  -w "\nHTTP Status: %{http_code}\n"

预期响应:

{
  "error": "not_found",
  "message": "Thread 'non-existent-thread' not found"
}

预期状态码: 404

验证点:

  • HTTP 状态码为 404
  • 响应体包含 error 字段

TC-T-010: POST /threads/search - 搜索 Threads

测试目的: 根据条件搜索 Threads

测试类型: 正向测试

前置条件: TC-T-001 已执行

curl 命令:

curl -X POST "$API_BASE_URL/threads/search" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "idle",
    "limit": 10,
    "offset": 0
  }' \
  -w "\nHTTP Status: %{http_code}\n"

预期响应:

[
  {
    "thread_id": "test-thread-001",
    "status": "idle",
    "metadata": {
      "title": "测试对话(已更新)",
      "owner": "test_user@example.com"
    },
    "created_at": "2024-01-01T00:00:00Z",
    "updated_at": "2024-01-01T01:00:00Z"
  }
]

预期状态码: 200

验证点:

  • HTTP 状态码为 200
  • 响应体为数组
  • 返回的 Thread 匹配搜索条件
  • status 为 "idle"

测试组 4: Thread State 操作

TC-T-011: GET /threads/{thread_id}/state - 获取 Thread 状态 (无关联 graph)

测试目的: 获取未关联 graph 的 Thread 状态

测试类型: 正向测试

前置条件: TC-T-001 已执行，THREAD_ID 已设置

curl 命令:

curl -X GET "$API_BASE_URL/threads/$THREAD_ID/state" \
  -H "Authorization: Bearer $API_TOKEN" \
  -w "\nHTTP Status: %{http_code}\n"

预期响应:

{
  "values": {},
  "next": [],
  "tasks": [],
  "interrupts": [],
  "metadata": {},
  "created_at": null,
  "checkpoint": {
    "checkpoint_id": null,
    "thread_id": "test-thread-001",
    "checkpoint_ns": ""
  },
  "parent_checkpoint": null,
  "checkpoint_id": null,
  "parent_checkpoint_id": null
}

预期状态码: 200

验证点:

  • HTTP 状态码为 200
  • values 为空对象
  • checkpoint_id 为 null

TC-T-012: GET /threads/{thread_id}/state - 获取 Thread 状态 (包含子图)

测试目的: 获取 Thread 状态时包含子图信息

测试类型: 正向测试

前置条件: TC-T-001 已执行，THREAD_ID 已设置

curl 命令:

curl -X GET "$API_BASE_URL/threads/$THREAD_ID/state?subgraphs=true" \
  -H "Authorization: Bearer $API_TOKEN" \
  -w "\nHTTP Status: %{http_code}\n"

预期响应:

{
  "values": {},
  "next": [],
  "tasks": [],
  "interrupts": [],
  "metadata": {},
  "created_at": null,
  "checkpoint": {
    "checkpoint_id": null,
    "thread_id": "test-thread-001",
    "checkpoint_ns": ""
  },
  "parent_checkpoint": null,
  "checkpoint_id": null,
  "parent_checkpoint_id": null
}

预期状态码: 200

验证点:

  • HTTP 状态码为 200

TC-T-013: GET /threads/{thread_id}/state - 获取 Thread 状态 (指定 checkpoint_ns)

测试目的: 使用 checkpoint_ns 参数获取 Thread 状态

测试类型: 正向测试

前置条件: TC-T-001 已执行，THREAD_ID 已设置

curl 命令:

curl -X GET "$API_BASE_URL/threads/$THREAD_ID/state?checkpoint_ns=test_ns" \
  -H "Authorization: Bearer $API_TOKEN" \
  -w "\nHTTP Status: %{http_code}\n"

预期响应:

{
  "values": {},
  "next": [],
  "tasks": [],
  "interrupts": [],
  "metadata": {},
  "created_at": null,
  "checkpoint": {
    "checkpoint_id": null,
    "thread_id": "test-thread-001",
    "checkpoint_ns": "test_ns"
  },
  "parent_checkpoint": null,
  "checkpoint_id": null,
  "parent_checkpoint_id": null
}

预期状态码: 200

验证点:

  • HTTP 状态码为 200

TC-T-014: POST /threads/{thread_id}/state - 更新 Thread 状态 (无 graph)

测试目的: 尝试更新未关联 graph 的 Thread 状态

测试类型: 异常测试

前置条件: TC-T-001 已执行，THREAD_ID 已设置

curl 命令:

curl -X POST "$API_BASE_URL/threads/$THREAD_ID/state" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "values": {
      "message": "test"
    }
  }' \
  -w "\nHTTP Status: %{http_code}\n"

预期响应:

{
  "error": "bad_request",
  "message": "Thread 'test-thread-001' has no associated graph. Cannot update state."
}

预期状态码: 400

验证点:

  • HTTP 状态码为 400
  • 响应体包含 error 字段

TC-T-015: POST /threads/{thread_id}/state - 获取 Thread 状态 (values=null)

测试目的: 使用 POST 方法获取 Thread 状态

测试类型: 正向测试

前置条件: TC-T-001 已执行，THREAD_ID 已设置

curl 命令:

curl -X POST "$API_BASE_URL/threads/$THREAD_ID/state" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "values": null,
    "subgraphs": false
  }' \
  -w "\nHTTP Status: %{http_code}\n"

预期响应:

{
  "values": {},
  "next": [],
  "tasks": [],
  "interrupts": [],
  "metadata": {},
  "created_at": null,
  "checkpoint": {
    "checkpoint_id": null,
    "thread_id": "test-thread-001",
    "checkpoint_ns": ""
  },
  "parent_checkpoint": null,
  "checkpoint_id": null,
  "parent_checkpoint_id": null
}

预期状态码: 200

验证点:

  • HTTP 状态码为 200

TC-T-016: GET /threads/{thread_id}/state/{checkpoint_id} - 获取指定 checkpoint 的状态

测试目的: 获取 Thread 在特定 checkpoint 的状态

测试类型: 正向测试

前置条件: TC-T-001 已执行，THREAD_ID 已设置

curl 命令:

curl -X GET "$API_BASE_URL/threads/$THREAD_ID/state/checkpoint-123" \
  -H "Authorization: Bearer $API_TOKEN" \
  -w "\nHTTP Status: %{http_code}\n"

预期响应:

{
  "error": "not_found",
  "message": "Thread 'test-thread-001' has no associated graph"
}

预期状态码: 404

验证点:

  • HTTP 状态码为 404

TC-T-017: POST /threads/{thread_id}/state/checkpoint - POST 方式获取 checkpoint 状态

测试目的: 使用 POST 方法获取特定 checkpoint 的状态

测试类型: 正向测试

前置条件: TC-T-001 已执行，THREAD_ID 已设置

curl 命令:

curl -X POST "$API_BASE_URL/threads/$THREAD_ID/state/checkpoint" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "checkpoint": {
      "checkpoint_id": "checkpoint-123",
      "checkpoint_ns": ""
    },
    "subgraphs": false
  }' \
  -w "\nHTTP Status: %{http_code}\n"

预期响应:

{
  "error": "not_found",
  "message": "Thread 'test-thread-001' has no associated graph"
}

预期状态码: 404

验证点:

  • HTTP 状态码为 404

TC-T-018: POST /threads/{thread_id}/state/checkpoint - 缺少 checkpoint_id

测试目的: 验证缺少 checkpoint_id 时返回 400

测试类型: 异常测试

前置条件: TC-T-001 已执行，THREAD_ID 已设置

curl 命令:

curl -X POST "$API_BASE_URL/threads/$THREAD_ID/state/checkpoint" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "checkpoint": {
      "checkpoint_ns": ""
    }
  }' \
  -w "\nHTTP Status: %{http_code}\n"

预期响应:

{
  "error": "bad_request",
  "message": "checkpoint_id is required in checkpoint configuration"
}

预期状态码: 400

验证点:

  • HTTP 状态码为 400
  • 响应体包含 error 字段

TC-T-019: GET /threads/{thread_id}/history - 获取 Thread 历史记录

测试目的: 获取 Thread 的 checkpoint 历史

测试类型: 正向测试

前置条件: TC-T-001 已执行，THREAD_ID 已设置

curl 命令:

curl -X GET "$API_BASE_URL/threads/$THREAD_ID/history" \
  -H "Authorization: Bearer $API_TOKEN" \
  -w "\nHTTP Status: %{http_code}\n"

预期响应:

[]

预期状态码: 200

验证点:

  • HTTP 状态码为 200
  • 响应体为数组

TC-T-020: GET /threads/{thread_id}/history - 使用 limit 参数

测试目的: 使用 limit 参数限制返回的历史记录数量

测试类型: 正向测试

前置条件: TC-T-001 已执行，THREAD_ID 已设置

curl 命令:

curl -X GET "$API_BASE_URL/threads/$THREAD_ID/history?limit=5" \
  -H "Authorization: Bearer $API_TOKEN" \
  -w "\nHTTP Status: %{http_code}\n"

预期响应:

[]

预期状态码: 200

验证点:

  • HTTP 状态码为 200

TC-T-021: GET /threads/{thread_id}/history - 使用 before 参数

测试目的: 使用 before 参数获取指定 checkpoint 之前的历史

测试类型: 正向测试

前置条件: TC-T-001 已执行，THREAD_ID 已设置

curl 命令:

curl -X GET "$API_BASE_URL/threads/$THREAD_ID/history?before=checkpoint-123&limit=10" \
  -H "Authorization: Bearer $API_TOKEN" \
  -w "\nHTTP Status: %{http_code}\n"

预期响应:

[]

预期状态码: 200

验证点:

  • HTTP 状态码为 200

TC-T-022: GET /threads/{thread_id}/history - 使用 subgraphs 参数

测试目的: 获取历史记录时包含子图信息

测试类型: 正向测试

前置条件: TC-T-001 已执行，THREAD_ID 已设置

curl 命令:

curl -X GET "$API_BASE_URL/threads/$THREAD_ID/history?subgraphs=true" \
  -H "Authorization: Bearer $API_TOKEN" \
  -w "\nHTTP Status: %{http_code}\n"

预期响应:

[]

预期状态码: 200

验证点:

  • HTTP 状态码为 200

TC-T-023: GET /threads/{thread_id}/history - 使用 metadata 参数

测试目的: 使用 metadata 参数过滤历史记录

测试类型: 正向测试

前置条件: TC-T-001 已执行，THREAD_ID 已设置

curl 命令:

curl -X GET "$API_BASE_URL/threads/$THREAD_ID/history?metadata=%7B%22source%22%3A%22agent%22%7D" \
  -H "Authorization: Bearer $API_TOKEN" \
  -w "\nHTTP Status: %{http_code}\n"

预期响应:

[]

预期状态码: 200

验证点:

  • HTTP 状态码为 200

TC-T-024: GET /threads/{thread_id}/history - 无效的 metadata JSON

测试目的: 验证无效的 metadata JSON 时返回 422

测试类型: 异常测试

前置条件: TC-T-001 已执行，THREAD_ID 已设置

curl 命令:

curl -X GET "$API_BASE_URL/threads/$THREAD_ID/history?metadata=invalid-json" \
  -H "Authorization: Bearer $API_TOKEN" \
  -w "\nHTTP Status: %{http_code}\n"

预期响应:

{
  "error": "validation_error",
  "message": "Invalid metadata query param: Expecting value: line 1 column 1 (char 0)"
}

预期状态码: 422

验证点:

  • HTTP 状态码为 422
  • 响应体包含 error 字段

TC-T-025: GET /threads/{thread_id}/history - limit 超出范围

测试目的: 验证 limit 超出范围时返回 422

测试类型: 异常测试

前置条件: TC-T-001 已执行，THREAD_ID 已设置

curl 命令:

curl -X GET "$API_BASE_URL/threads/$THREAD_ID/history?limit=2000" \
  -H "Authorization: Bearer $API_TOKEN" \
  -w "\nHTTP Status: %{http_code}\n"

预期响应:

{
  "error": "validation_error",
  "message": "Invalid limit; must be an integer between 1 and 1000"
}

预期状态码: 422

验证点:

  • HTTP 状态码为 422
  • 响应体包含 error 字段

TC-T-026: POST /threads/{thread_id}/history - POST 方式获取历史

测试目的: 使用 POST 方法获取 Thread 历史记录

测试类型: 正向测试

前置条件: TC-T-001 已执行，THREAD_ID 已设置

curl 命令:

curl -X POST "$API_BASE_URL/threads/$THREAD_ID/history" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "limit": 10,
    "before": null,
    "metadata": null,
    "checkpoint": null,
    "subgraphs": false,
    "checkpoint_ns": null
  }' \
  -w "\nHTTP Status: %{http_code}\n"

预期响应:

[]

预期状态码: 200

验证点:

  • HTTP 状态码为 200

TC-T-027: DELETE /threads/{thread_id} - 删除 Thread

测试目的: 删除指定的 Thread

测试类型: 正向测试

前置条件: TC-T-001 已执行，THREAD_ID 已设置

curl 命令:

curl -X DELETE "$API_BASE_URL/threads/$THREAD_ID" \
  -H "Authorization: Bearer $API_TOKEN" \
  -w "\nHTTP Status: %{http_code}\n"

预期响应:

{
  "status": "deleted"
}

预期状态码: 200

验证点:

  • HTTP 状态码为 200
  • 响应体包含 status 字段，值为 "deleted"

TC-T-028: DELETE /threads/{thread_id} - 删除不存在的 Thread

测试目的: 验证删除不存在的 Thread 时返回 404

测试类型: 异常测试

前置条件: 无

curl 命令:

curl -X DELETE "$API_BASE_URL/threads/non-existent-thread" \
  -H "Authorization: Bearer $API_TOKEN" \
  -w "\nHTTP Status: %{http_code}\n"

预期响应:

{
  "error": "not_found",
  "message": "Thread 'non-existent-thread' not found"
}

预期状态码: 404

验证点:

  • HTTP 状态码为 404
  • 响应体包含 error 字段

Runs 模块测试

测试组 5: Runs CRUD 操作

注意: 以下测试用例假设已存在一个 Assistant 和 Thread 在执行前需要先创建 Assistant 和 Thread

TC-R-001: POST /threads/{thread_id}/runs - 创建 Run (正向测试)

测试目的: 成功创建一个新的 Run

测试类型: 正向测试

前置条件:

  • 已创建 Assistant (assistant_id: "agent")
  • 已创建 Thread (thread_id: "test-thread-001")

curl 命令:

curl -X POST "$API_BASE_URL/threads/test-thread-001/runs" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "assistant_id": "agent",
    "input": {
      "messages": [
        {
          "role": "user",
          "content": "你好，请介绍一下自己"
        }
      ]
    },
    "config": {
      "configurable": {
        "model": "gpt-4"
      }
    }
  }' \
  -w "\nHTTP Status: %{http_code}\n"

预期响应:

{
  "run_id": "550e8400-e29b-41d4-a716-446655440001",
  "thread_id": "test-thread-001",
  "assistant_id": "agent",
  "status": "pending",
  "input": {
    "messages": [
      {
        "role": "user",
        "content": "你好，请介绍一下自己"
      }
    ]
  },
  "output": null,
  "error_message": null,
  "config": {
    "configurable": {
      "model": "gpt-4"
    }
  },
  "context": {},
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-01T00:00:00Z"
}

预期状态码: 201

验证点:

  • HTTP 状态码为 201
  • 响应体包含 run_id 字段
  • status 为 "pending"
  • assistant_id 与请求中的值一致
  • thread_id 与请求路径中的值一致

依赖设置: 保存返回的 run_id 到环境变量 RUN_ID

TC-R-002: POST /threads/{thread_id}/runs - 使用 graph_id 创建 Run

测试目的: 使用 graph_id 而非 assistant_id 创建 Run

测试类型: 正向测试

前置条件:

  • 已创建 Thread (thread_id: "test-thread-001")

curl 命令:

curl -X POST "$API_BASE_URL/threads/test-thread-001/runs" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "assistant_id": "agent",
    "input": {
      "messages": [
        {
          "role": "user",
          "content": "测试消息"
        }
      ]
    }
  }' \
  -w "\nHTTP Status: %{http_code}\n"

预期响应:

{
  "run_id": "550e8400-e29b-41d4-a716-446655440002",
  "thread_id": "test-thread-001",
  "assistant_id": "agent",
  "status": "pending",
  "input": {
    "messages": [
      {
        "role": "user",
        "content": "测试消息"
      }
    ]
  },
  "output": null,
  "error_message": null,
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-01T00:00:00Z"
}

预期状态码: 201

验证点:

  • HTTP 状态码为 201
  • run_id 为 UUID 格式

TC-R-003: POST /threads/{thread_id}/runs - 不存在的 Assistant

测试目的: 验证使用不存在的 assistant_id 时返回 404

测试类型: 异常测试

前置条件: 无

curl 命令:

curl -X POST "$API_BASE_URL/threads/test-thread-001/runs" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "assistant_id": "non-existent-assistant",
    "input": {
      "messages": [
        {
          "role": "user",
          "content": "测试"
        }
      ]
    }
  }' \
  -w "\nHTTP Status: %{http_code}\n"

预期响应:

{
  "error": "not_found",
  "message": "Assistant 'non-existent-assistant' not found"
}

预期状态码: 404

验证点:

  • HTTP 状态码为 404
  • 响应体包含 error 字段

TC-R-004: POST /threads/{thread_id}/runs - 同时指定 configurable 和 context

测试目的: 验证同时指定 configurable 和 context 时返回 400

测试类型: 异常测试

前置条件: 无

curl 命令:

curl -X POST "$API_BASE_URL/threads/test-thread-001/runs" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "assistant_id": "agent",
    "input": {},
    "config": {
      "configurable": {
        "model": "gpt-4"
      }
    },
    "context": {
      "model": "gpt-4"
    }
  }' \
  -w "\nHTTP Status: %{http_code}\n"

预期响应:

{
  "error": "bad_request",
  "message": "Cannot specify both configurable and context. Prefer setting context alone. Context was introduced in LangGraph 0.6.0 and is the long term planned replacement for configurable."
}

预期状态码: 400

验证点:

  • HTTP 状态码为 400
  • 响应体包含 error 字段

TC-R-005: GET /threads/{thread_id}/runs - 列出 Runs

测试目的: 获取指定 Thread 的所有 Runs

测试类型: 正向测试

前置条件: TC-R-001 已执行

curl 命令:

curl -X GET "$API_BASE_URL/threads/test-thread-001/runs" \
  -H "Authorization: Bearer $API_TOKEN" \
  -w "\nHTTP Status: %{http_code}\n"

预期响应:

[
  {
    "run_id": "550e8400-e29b-41d4-a716-446655440001",
    "thread_id": "test-thread-001",
    "assistant_id": "agent",
    "status": "success",
    "input": {
      "messages": [
        {
          "role": "user",
          "content": "你好，请介绍一下自己"
        }
      ]
    },
    "output": {
      "messages": [
        {
          "role": "assistant",
          "content": "你好！我是一个AI助手..."
        }
      ]
    },
    "created_at": "2024-01-01T00:00:00Z",
    "updated_at": "2024-01-01T00:01:00Z"
  }
]

预期状态码: 200

验证点:

  • HTTP 状态码为 200
  • 响应体为数组
  • 数组中包含 TC-R-001 创建的 Run

TC-R-006: GET /threads/{thread_id}/runs - 使用 limit 参数

测试目的: 使用 limit 参数限制返回的 Runs 数量

测试类型: 正向测试

前置条件: TC-R-001 已执行

curl 命令:

curl -X GET "$API_BASE_URL/threads/test-thread-001/runs?limit=1" \
  -H "Authorization: Bearer $API_TOKEN" \
  -w "\nHTTP Status: %{http_code}\n"

预期响应:

[
  {
    "run_id": "550e8400-e29b-41d4-a716-446655440001",
    "thread_id": "test-thread-001",
    "assistant_id": "agent",
    "status": "success",
    "created_at": "2024-01-01T00:00:00Z",
    "updated_at": "2024-01-01T00:01:00Z"
  }
]

预期状态码: 200

验证点:

  • HTTP 状态码为 200
  • 返回的 Runs 数量不超过 limit 值

TC-R-007: GET /threads/{thread_id}/runs - 使用 offset 参数

测试目的: 使用 offset 参数进行分页

测试类型: 正向测试

前置条件: TC-R-001 已执行

curl 命令:

curl -X GET "$API_BASE_URL/threads/test-thread-001/runs?offset=0&limit=10" \
  -H "Authorization: Bearer $API_TOKEN" \
  -w "\nHTTP Status: %{http_code}\n"

预期响应:

[
  {
    "run_id": "550e8400-e29b-41d4-a716-446655440001",
    "thread_id": "test-thread-001",
    "assistant_id": "agent",
    "status": "success",
    "created_at": "2024-01-01T00:00:00Z",
    "updated_at": "2024-01-01T00:01:00Z"
  }
]

预期状态码: 200

验证点:

  • HTTP 状态码为 200

TC-R-008: GET /threads/{thread_id}/runs - 使用 status 过滤

测试目的: 使用 status 参数过滤 Runs

测试类型: 正向测试

前置条件: TC-R-001 已执行

curl 命令:

curl -X GET "$API_BASE_URL/threads/test-thread-001/runs?status=success" \
  -H "Authorization: Bearer $API_TOKEN" \
  -w "\nHTTP Status: %{http_code}\n"

预期响应:

[
  {
    "run_id": "550e8400-e29b-41d4-a716-446655440001",
    "thread_id": "test-thread-001",
    "assistant_id": "agent",
    "status": "success",
    "created_at": "2024-01-01T00:00:00Z",
    "updated_at": "2024-01-01T00:01:00Z"
  }
]

预期状态码: 200

验证点:

  • HTTP 状态码为 200
  • 返回的 Runs 都匹配指定的 status

TC-R-009: GET /threads/{thread_id}/runs/{run_id} - 获取指定 Run

测试目的: 根据 ID 获取单个 Run 详情

测试类型: 正向测试

前置条件: TC-R-001 已执行，RUN_ID 已设置

curl 命令:

curl -X GET "$API_BASE_URL/threads/test-thread-001/runs/$RUN_ID" \
  -H "Authorization: Bearer $API_TOKEN" \
  -w "\nHTTP Status: %{http_code}\n"

预期响应:

{
  "run_id": "550e8400-e29b-41d4-a716-446655440001",
  "thread_id": "test-thread-001",
  "assistant_id": "agent",
  "status": "success",
  "input": {
    "messages": [
      {
        "role": "user",
        "content": "你好，请介绍一下自己"
      }
    ]
  },
  "output": {
    "messages": [
      {
        "role": "assistant",
        "content": "你好！我是一个AI助手..."
      }
    ]
  },
  "error_message": null,
  "config": {
    "configurable": {
      "model": "gpt-4"
    }
  },
  "context": {},
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-01T00:01:00Z"
}

预期状态码: 200

验证点:

  • HTTP 状态码为 200
  • run_id 与请求路径中的 ID 一致
  • output 包含执行结果

TC-R-010: GET /threads/{thread_id}/runs/{run_id} - 获取不存在的 Run

测试目的: 验证查询不存在的 Run 时返回 404

测试类型: 异常测试

前置条件: 无

curl 命令:

curl -X GET "$API_BASE_URL/threads/test-thread-001/runs/non-existent-run" \
  -H "Authorization: Bearer $API_TOKEN" \
  -w "\nHTTP Status: %{http_code}\n"

预期响应:

{
  "error": "not_found",
  "message": "Run 'non-existent-run' not found"
}

预期状态码: 404

验证点:

  • HTTP 状态码为 404
  • 响应体包含 error 字段

TC-R-011: PATCH /threads/{thread_id}/runs/{run_id} - 更新 Run 状态 (interrupted)

测试目的: 将 Run 状态更新为 interrupted

测试类型: 正向测试

前置条件: TC-R-001 已执行，RUN_ID 已设置

curl 命令:

curl -X PATCH "$API_BASE_URL/threads/test-thread-001/runs/$RUN_ID" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "interrupted"
  }' \
  -w "\nHTTP Status: %{http_code}\n"

预期响应:

{
  "run_id": "550e8400-e29b-41d4-a716-446655440001",
  "thread_id": "test-thread-001",
  "assistant_id": "agent",
  "status": "interrupted",
  "input": {
    "messages": [
      {
        "role": "user",
        "content": "你好，请介绍一下自己"
      }
    ]
  },
  "output": {
    "messages": [
      {
        "role": "assistant",
        "content": "你好！我是一个AI助手..."
      }
    ]
  },
  "error_message": null,
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-01T00:02:00Z"
}

预期状态码: 200

验证点:

  • HTTP 状态码为 200
  • status 已更新为 "interrupted"
  • updated_at 时间戳已更新

TC-R-012: PATCH /threads/{thread_id}/runs/{run_id} - 更新不存在的 Run

测试目的: 验证更新不存在的 Run 时返回 404

测试类型: 异常测试

前置条件: 无

curl 命令:

curl -X PATCH "$API_BASE_URL/threads/test-thread-001/runs/non-existent-run" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "interrupted"
  }' \
  -w "\nHTTP Status: %{http_code}\n"

预期响应:

{
  "error": "not_found",
  "message": "Run 'non-existent-run' not found"
}

预期状态码: 404

验证点:

  • HTTP 状态码为 404
  • 响应体包含 error 字段

TC-R-013: GET /threads/{thread_id}/runs/{run_id}/join - 等待 Run 完成

测试目的: 等待 Run 执行完成并返回输出

测试类型: 正向测试

前置条件: TC-R-001 已执行，RUN_ID 已设置

curl 命令:

curl -X GET "$API_BASE_URL/threads/test-thread-001/runs/$RUN_ID/join" \
  -H "Authorization: Bearer $API_TOKEN" \
  -w "\nHTTP Status: %{http_code}\n"

预期响应:

{
  "messages": [
    {
      "role": "assistant",
      "content": "你好！我是一个AI助手..."
    }
  ]
}

预期状态码: 200

验证点:

  • HTTP 状态码为 200
  • 响应体包含 Run 的输出

TC-R-014: POST /threads/{thread_id}/runs/wait - 创建并等待 Run

测试目的: 创建 Run 并同步等待其完成

测试类型: 正向测试

前置条件:

  • 已创建 Thread (thread_id: "test-thread-001")

curl 命令:

curl -X POST "$API_BASE_URL/threads/test-thread-001/runs/wait" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "assistant_id": "agent",
    "input": {
      "messages": [
        {
          "role": "user",
          "content": "简单测试"
        }
      ]
    }
  }' \
  -w "\nHTTP Status: %{http_code}\n"

预期响应:

{
  "messages": [
    {
      "role": "assistant",
      "content": "收到你的消息..."
    }
  ]
}

预期状态码: 200

验证点:

  • HTTP 状态码为 200
  • 响应体包含 Run 的输出

TC-R-015: POST /threads/{thread_id}/runs/stream - 流式创建 Run

测试目的: 创建 Run 并流式返回执行结果

测试类型: 正向测试

前置条件:

  • 已创建 Thread (thread_id: "test-thread-001")

curl 命令:

curl -N -X POST "$API_BASE_URL/threads/test-thread-001/runs/stream" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "assistant_id": "agent",
    "input": {
      "messages": [
        {
          "role": "user",
          "content": "流式测试"
        }
      ]
    }
  }' \
  -w "\nHTTP Status: %{http_code}\n"

预期响应:

event: data
data: {"event":"values","data":{"messages":[{"role":"assistant","content":"收到..."}]}}

event: end
data: {}

预期状态码: 200

验证点:

  • HTTP 状态码为 200
  • Content-Type 为 "text/event-stream"
  • 响应包含 SSE 事件流
  • 最后包含 event: end 事件

TC-R-016: GET /threads/{thread_id}/runs/{run_id}/stream - 流式获取 Run

测试目的: 流式获取已创建 Run 的执行结果

测试类型: 正向测试

前置条件: TC-R-001 已执行，RUN_ID 已设置

curl 命令:

curl -N -X GET "$API_BASE_URL/threads/test-thread-001/runs/$RUN_ID/stream" \
  -H "Authorization: Bearer $API_TOKEN" \
  -w "\nHTTP Status: %{http_code}\n"

预期响应:

event: end
data: {}

预期状态码: 200

验证点:

  • HTTP 状态码为 200
  • Content-Type 为 "text/event-stream"
  • 响应包含 SSE 事件流

TC-R-017: GET /threads/{thread_id}/runs/{run_id}/stream - 使用 Last-Event-ID

测试目的: 使用 Last-Event-ID 头进行断点续传

测试类型: 正向测试

前置条件: TC-R-001 已执行，RUN_ID 已设置

curl 命令:

curl -N -X GET "$API_BASE_URL/threads/test-thread-001/runs/$RUN_ID/stream" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Last-Event-ID: some_event_id" \
  -w "\nHTTP Status: %{http_code}\n"

预期响应:

event: end
data: {}

预期状态码: 200

验证点:

  • HTTP 状态码为 200

TC-R-018: POST /threads/{thread_id}/runs/{run_id}/cancel - 取消 Run (action=cancel)

测试目的: 取消正在执行的 Run

测试类型: 正向测试

前置条件: TC-R-001 已执行，RUN_ID 已设置

curl 命令:

curl -X POST "$API_BASE_URL/threads/test-thread-001/runs/$RUN_ID/cancel?action=cancel&wait=0" \
  -H "Authorization: Bearer $API_TOKEN" \
  -w "\nHTTP Status: %{http_code}\n"

预期响应:

{
  "run_id": "550e8400-e29b-41d4-a716-446655440001",
  "thread_id": "test-thread-001",
  "assistant_id": "agent",
  "status": "interrupted",
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-01T00:03:00Z"
}

预期状态码: 200

验证点:

  • HTTP 状态码为 200
  • status 为 "interrupted"

TC-R-019: POST /threads/{thread_id}/runs/{run_id}/cancel - 中断 Run (action=interrupt)

测试目的: 协作式中断正在执行的 Run

测试类型: 正向测试

前置条件: TC-R-001 已执行，RUN_ID 已设置

curl 命令:

curl -X POST "$API_BASE_URL/threads/test-thread-001/runs/$RUN_ID/cancel?action=interrupt&wait=0" \
  -H "Authorization: Bearer $API_TOKEN" \
  -w "\nHTTP Status: %{http_code}\n"

预期响应:

{
  "run_id": "550e8400-e29b-41d4-a716-446655440001",
  "thread_id": "test-thread-001",
  "assistant_id": "agent",
  "status": "interrupted",
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-01T00:03:00Z"
}

预期状态码: 200

验证点:

  • HTTP 状态码为 200
  • status 为 "interrupted"

TC-R-020: POST /threads/{thread_id}/runs/{run_id}/cancel - 等待任务完成

测试目的: 取消 Run 并等待后台任务完成

测试类型: 正向测试

前置条件: TC-R-001 已执行，RUN_ID 已设置

curl 命令:

curl -X POST "$API_BASE_URL/threads/test-thread-001/runs/$RUN_ID/cancel?action=cancel&wait=1" \
  -H "Authorization: Bearer $API_TOKEN" \
  -w "\nHTTP Status: %{http_code}\n"

预期响应:

{
  "run_id": "550e8400-e29b-41d4-a716-446655440001",
  "thread_id": "test-thread-001",
  "assistant_id": "agent",
  "status": "interrupted",
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-01T00:03:00Z"
}

预期状态码: 200

验证点:

  • HTTP 状态码为 200

TC-R-021: DELETE /threads/{thread_id}/runs/{run_id} - 删除 Run

测试目的: 删除指定的 Run

测试类型: 正向测试

前置条件: TC-R-001 已执行，RUN_ID 已设置

curl 命令:

curl -X DELETE "$API_BASE_URL/threads/test-thread-001/runs/$RUN_ID" \
  -H "Authorization: Bearer $API_TOKEN" \
  -w "\nHTTP Status: %{http_code}\n"

预期响应: (无响应体)

预期状态码: 204

验证点:

  • HTTP 状态码为 204
  • 响应体为空

TC-R-022: DELETE /threads/{thread_id}/runs/{run_id} - 删除不存在的 Run

测试目的: 验证删除不存在的 Run 时返回 404

测试类型: 异常测试

前置条件: 无

curl 命令:

curl -X DELETE "$API_BASE_URL/threads/test-thread-001/runs/non-existent-run" \
  -H "Authorization: Bearer $API_TOKEN" \
  -w "\nHTTP Status: %{http_code}\n"

预期响应:

{
  "error": "not_found",
  "message": "Run 'non-existent-run' not found"
}

预期状态码: 404

验证点:

  • HTTP 状态码为 404
  • 响应体包含 error 字段

TC-R-023: DELETE /threads/{thread_id}/runs/{run_id} - 删除活跃 Run (force=0)

测试目的: 验证删除活跃 Run 且不强制时返回 409

测试类型: 异常测试

前置条件: 存在活跃状态的 Run

curl 命令:

curl -X DELETE "$API_BASE_URL/threads/test-thread-001/runs/active-run-id?force=0" \
  -H "Authorization: Bearer $API_TOKEN" \
  -w "\nHTTP Status: %{http_code}\n"

预期响应:

{
  "error": "conflict",
  "message": "Run is active. Retry with force=1 to cancel and delete."
}

预期状态码: 409

验证点:

  • HTTP 状态码为 409
  • 响应体包含 error 字段

TC-R-024: DELETE /threads/{thread_id}/runs/{run_id} - 强制删除活跃 Run

测试目的: 强制删除活跃状态的 Run

测试类型: 正向测试

前置条件: 存在活跃状态的 Run

curl 命令:

curl -X DELETE "$API_BASE_URL/threads/test-thread-001/runs/active-run-id?force=1" \
  -H "Authorization: Bearer $API_TOKEN" \
  -w "\nHTTP Status: %{http_code}\n"

预期响应: (无响应体)

预期状态码: 204

验证点:

  • HTTP 状态码为 204
  • 响应体为空

Store 模块测试

测试组 6: Store CRUD 操作

TC-S-001: PUT /store/items - 存储数据

测试目的: 成功存储数据到 LangGraph Store

测试类型: 正向测试

前置条件: 无

curl 命令:

curl -X PUT "$API_BASE_URL/store/items" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "test-key-001",
    "namespace": ["test", "data"],
    "value": {
      "message": "Hello, World!",
      "timestamp": "2024-01-01T00:00:00Z"
    }
  }' \
  -w "\nHTTP Status: %{http_code}\n"

预期响应:

{
  "status": "stored"
}

预期状态码: 200

验证点:

  • HTTP 状态码为 200
  • 响应体包含 status 字段，值为 "stored"

TC-S-002: PUT /store/items - 存储数据 (默认 namespace)

测试目的: 使用默认 namespace 存储数据

测试类型: 正向测试

前置条件: 无

curl 命令:

curl -X PUT "$API_BASE_URL/store/items" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "test-key-002",
    "namespace": [],
    "value": {
      "data": "default namespace test"
    }
  }' \
  -w "\nHTTP Status: %{http_code}\n"

预期响应:

{
  "status": "stored"
}

预期状态码: 200

验证点:

  • HTTP 状态码为 200

TC-S-003: GET /store/items - 获取数据 (使用 query 参数)

测试目的: 使用 query 参数获取存储的数据

测试类型: 正向测试

前置条件: TC-S-001 已执行

curl 命令:

curl -X GET "$API_BASE_URL/store/items?key=test-key-001&namespace=test.data" \
  -H "Authorization: Bearer $API_TOKEN" \
  -w "\nHTTP Status: %{http_code}\n"

预期响应:

{
  "key": "test-key-001",
  "value": {
    "message": "Hello, World!",
    "timestamp": "2024-01-01T00:00:00Z"
  },
  "namespace": ["users", "test_user@example.com", "test", "data"]
}

预期状态码: 200

验证点:

  • HTTP 状态码为 200
  • key 与请求中的值一致
  • value 包含存储的数据
  • namespace 包含用户命名空间前缀

TC-S-004: GET /store/items - 获取数据 (使用数组 namespace)

测试目的: 使用数组形式的 namespace 参数

测试类型: 正向测试

前置条件: TC-S-001 已执行

curl 命令:

curl -X GET "$API_BASE_URL/store/items?key=test-key-001&namespace[]=test&namespace[]=data" \
  -H "Authorization: Bearer $API_TOKEN" \
  -w "\nHTTP Status: %{http_code}\n"

预期响应:

{
  "key": "test-key-001",
  "value": {
    "message": "Hello, World!",
    "timestamp": "2024-01-01T00:00:00Z"
  },
  "namespace": ["users", "test_user@example.com", "test", "data"]
}

预期状态码: 200

验证点:

  • HTTP 状态码为 200

TC-S-005: GET /store/items - 获取不存在的数据

测试目的: 验证获取不存在的数据时返回 404

测试类型: 异常测试

前置条件: 无

curl 命令:

curl -X GET "$API_BASE_URL/store/items?key=non-existent-key" \
  -H "Authorization: Bearer $API_TOKEN" \
  -w "\nHTTP Status: %{http_code}\n"

预期响应:

{
  "error": "not_found",
  "message": "Item not found"
}

预期状态码: 404

验证点:

  • HTTP 状态码为 404
  • 响应体包含 error 字段

TC-S-006: GET /store/items - 缺少 key 参数

测试目的: 验证缺少 key 参数时的行为

测试类型: 边界测试

前置条件: 无

curl 命令:

curl -X GET "$API_BASE_URL/store/items" \
  -H "Authorization: Bearer $API_TOKEN" \
  -w "\nHTTP Status: %{http_code}\n"

预期响应:

{
  "error": "validation_error",
  "message": "Missing 'key' parameter"
}

预期状态码: 422

验证点:

  • HTTP 状态码为 422
  • 响应体包含 error 字段

TC-S-007: DELETE /store/items - 删除数据 (使用 body)

测试目的: 使用 JSON body 删除存储的数据

测试类型: 正向测试

前置条件: TC-S-001 已执行

curl 命令:

curl -X DELETE "$API_BASE_URL/store/items" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "test-key-001",
    "namespace": ["test", "data"]
  }' \
  -w "\nHTTP Status: %{http_code}\n"

预期响应:

{
  "status": "deleted"
}

预期状态码: 200

验证点:

  • HTTP 状态码为 200
  • 响应体包含 status 字段，值为 "deleted"

TC-S-008: DELETE /store/items - 删除数据 (使用 query 参数)

测试目的: 使用 query 参数删除存储的数据

测试类型: 正向测试

前置条件: TC-S-002 已执行

curl 命令:

curl -X DELETE "$API_BASE_URL/store/items?key=test-key-002" \
  -H "Authorization: Bearer $API_TOKEN" \
  -w "\nHTTP Status: %{http_code}\n"

预期响应:

{
  "status": "deleted"
}

预期状态码: 200

验证点:

  • HTTP 状态码为 200

TC-S-009: DELETE /store/items - 缺少 key 参数

测试目的: 验证删除时缺少 key 参数返回 422

测试类型: 异常测试

前置条件: 无

curl 命令:

curl -X DELETE "$API_BASE_URL/store/items" \
  -H "Authorization: Bearer $API_TOKEN" \
  -w "\nHTTP Status: %{http_code}\n"

预期响应:

{
  "error": "validation_error",
  "message": "Missing 'key' parameter"
}

预期状态码: 422

验证点:

  • HTTP 状态码为 422
  • 响应体包含 error 字段

TC-S-010: POST /store/items/search - 搜索数据

测试目的: 搜索存储的数据

测试类型: 正向测试

前置条件: TC-S-001 已执行

curl 命令:

curl -X POST "$API_BASE_URL/store/items/search" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "namespace_prefix": ["test"],
    "query": "test",
    "limit": 10,
    "offset": 0
  }' \
  -w "\nHTTP Status: %{http_code}\n"

预期响应:

{
  "items": [
    {
      "key": "test-key-001",
      "value": {
        "message": "Hello, World!",
        "timestamp": "2024-01-01T00:00:00Z"
      },
      "namespace": ["users", "test_user@example.com", "test", "data"]
    }
  ],
  "total": 1,
  "limit": 10,
  "offset": 0
}

预期状态码: 200

验证点:

  • HTTP 状态码为 200
  • 响应体包含 items 数组
  • 响应体包含 total、limit、offset 字段

TC-S-011: POST /store/items/search - 使用 limit 和 offset

测试目的: 使用分页参数搜索数据

测试类型: 正向测试

前置条件: TC-S-001 已执行

curl 命令:

curl -X POST "$API_BASE_URL/store/items/search" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "namespace_prefix": [],
    "query": "",
    "limit": 5,
    "offset": 0
  }' \
  -w "\nHTTP Status: %{http_code}\n"

预期响应:

{
  "items": [],
  "total": 0,
  "limit": 5,
  "offset": 0
}

预期状态码: 200

验证点:

  • HTTP 状态码为 200
  • 返回的 items 数量不超过 limit

TC-S-012: POST /store/items/search - 空搜索结果

测试目的: 验证搜索无结果时的响应

测试类型: 正向测试

前置条件: 无

curl 命令:

curl -X POST "$API_BASE_URL/store/items/search" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "namespace_prefix": ["nonexistent"],
    "query": "test",
    "limit": 10,
    "offset": 0
  }' \
  -w "\nHTTP Status: %{http_code}\n"

预期响应:

{
  "items": [],
  "total": 0,
  "limit": 10,
  "offset": 0
}

预期状态码: 200

验证点:

  • HTTP 状态码为 200
  • items 为空数组
  • total 为 0

异常场景测试

测试组 7: 认证和授权测试

TC-E-001: 无 Token 访问受保护端点

测试目的: 验证未提供 Token 时返回 401

测试类型: 异常测试

curl 命令:

curl -X GET "$API_BASE_URL/assistants" \
  -w "\nHTTP Status: %{http_code}\n"

预期响应:

{
  "error": "unauthorized",
  "message": "Authentication required"
}

预期状态码: 401

验证点:

  • HTTP 状态码为 401
  • 响应体包含 error 字段

TC-E-002: 无效 Token 访问受保护端点

测试目的: 验证使用无效 Token 时返回 401

测试类型: 异常测试

curl 命令:

curl -X GET "$API_BASE_URL/assistants" \
  -H "Authorization: Bearer invalid_token" \
  -w "\nHTTP Status: %{http_code}\n"

预期响应:

{
  "error": "unauthorized",
  "message": "Invalid authentication token"
}

预期状态码: 401

验证点:

  • HTTP 状态码为 401
  • 响应体包含 error 字段

TC-E-003: 访问其他用户的资源

测试目的: 验证用户无法访问其他用户的资源

测试类型: 异常测试

curl 命令:

curl -X GET "$API_BASE_URL/threads/other-user-thread" \
  -H "Authorization: Bearer $API_TOKEN" \
  -w "\nHTTP Status: %{http_code}\n"

预期响应:

{
  "error": "not_found",
  "message": "Thread 'other-user-thread' not found"
}

预期状态码: 404

验证点:

  • HTTP 状态码为 404
  • 响应体包含 error 字段

测试组 8: 输入验证测试

TC-E-004: 无效的 JSON 格式

测试目的: 验证无效 JSON 格式时返回 400

测试类型: 异常测试

curl 命令:

curl -X POST "$API_BASE_URL/assistants" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{invalid json}' \
  -w "\nHTTP Status: %{http_code}\n"

预期响应:

{
  "error": "bad_request",
  "message": "Invalid JSON format"
}

预期状态码: 400

验证点:

  • HTTP 状态码为 400
  • 响应体包含 error 字段

TC-E-005: 缺少 Content-Type 头

测试目的: 验证缺少 Content-Type 头时的行为

测试类型: 边界测试

curl 命令:

curl -X POST "$API_BASE_URL/assistants" \
  -H "Authorization: Bearer $API_TOKEN" \
  -d '{"name":"test"}' \
  -w "\nHTTP Status: %{http_code}\n"

预期响应:

{
  "error": "unsupported_media_type",
  "message": "Content-Type must be application/json"
}

预期状态码: 415

验证点:

  • HTTP 状态码为 415
  • 响应体包含 error 字段

TC-E-006: 超长的字段值

测试目的: 验证超长字段值时的处理

测试类型: 边界测试

curl 命令:

curl -X POST "$API_BASE_URL/assistants" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "assistant_id": "'$(python3 -c 'print("a"*10000)')'",
    "name": "test",
    "graph_id": "agent"
  }' \
  -w "\nHTTP Status: %{http_code}\n"

预期响应:

{
  "error": "validation_error",
  "message": "Field value too long"
}

预期状态码: 422

验证点:

  • HTTP 状态码为 422
  • 响应体包含 error 字段

测试组 9: 边界条件测试

TC-E-007: 空的请求体

测试目的: 验证空请求体时的行为

测试类型: 边界测试

curl 命令:

curl -X POST "$API_BASE_URL/assistants" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}' \
  -w "\nHTTP Status: %{http_code}\n"

预期响应:

{
  "error": "validation_error",
  "message": "Validation failed",
  "details": {
    "field": "graph_id",
    "reason": "field required"
  }
}

预期状态码: 422

验证点:

  • HTTP 状态码为 422
  • 响应体包含 error 字段

TC-E-008: limit 参数为 0

测试目的: 验证 limit=0 时的行为

测试类型: 边界测试

curl 命令:

curl -X GET "$API_BASE_URL/threads/test-thread-001/history?limit=0" \
  -H "Authorization: Bearer $API_TOKEN" \
  -w "\nHTTP Status: %{http_code}\n"

预期响应:

{
  "error": "validation_error",
  "message": "Invalid limit; must be an integer between 1 and 1000"
}

预期状态码: 422

验证点:

  • HTTP 状态码为 422

TC-E-009: limit 参数为负数

测试目的: 验证 limit 为负数时的行为

测试类型: 边界测试

curl 命令:

curl -X GET "$API_BASE_URL/threads/test-thread-001/history?limit=-1" \
  -H "Authorization: Bearer $API_TOKEN" \
  -w "\nHTTP Status: %{http_code}\n"

预期响应:

{
  "error": "validation_error",
  "message": "Invalid limit; must be an integer between 1 and 1000"
}

预期状态码: 422

验证点:

  • HTTP 状态码为 422

TC-E-010: offset 参数为负数

测试目的: 验证 offset 为负数时的行为

测试类型: 边界测试

curl 命令:

curl -X GET "$API_BASE_URL/threads/test-thread-001/history?offset=-1" \
  -H "Authorization: Bearer $API_TOKEN" \
  -w "\nHTTP Status: %{http_code}\n"

预期响应:

{
  "error": "validation_error",
  "message": "Invalid offset; must be a non-negative integer"
}

预期状态码: 422

验证点:

  • HTTP 状态码为 422

测试组 10: 并发和竞态条件测试

TC-E-011: 并发创建相同 ID 的 Thread

测试目的: 验证并发创建相同 ID 的 Thread 时的行为

测试类型: 并发测试

curl 命令:

# 在两个终端中同时执行
curl -X POST "$API_BASE_URL/threads" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "thread_id": "concurrent-thread-001",
    "metadata": {"source": "terminal1"}
  }' \
  -w "\nHTTP Status: %{http_code}\n"

预期响应: 终端 1:

{
  "thread_id": "concurrent-thread-001",
  "status": "idle",
  ...
}

终端 2:

{
  "error": "conflict",
  "message": "Thread 'concurrent-thread-001' already exists"
}

预期状态码: 201 或 409

验证点:

  • 一个请求成功 (201)
  • 另一个请求返回冲突 (409)

TC-E-012: 并发更新同一个 Thread

测试目的: 验证并发更新同一个 Thread 时的行为

测试类型: 并发测试

curl 命令:

# 在两个终端中同时执行
curl -X PATCH "$API_BASE_URL/threads/test-thread-001" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "metadata": {"source": "terminal1"}
  }' \
  -w "\nHTTP Status: %{http_code}\n"

预期响应:

{
  "thread_id": "test-thread-001",
  "status": "idle",
  "metadata": {
    "source": "terminal1" 或 "terminal2",
    ...
  },
  ...
}

预期状态码: 200

验证点:

  • 两个请求都成功
  • 最终状态包含其中一个更新

测试组 11: 性能测试

TC-E-013: 大量数据查询

测试目的: 测试查询大量数据时的性能

测试类型: 性能测试

curl 命令:

time curl -X GET "$API_BASE_URL/assistants" \
  -H "Authorization: Bearer $API_TOKEN" \
  -w "\nHTTP Status: %{http_code}\nTotal Time: %{time_total}s\n"

预期响应:

{
  "assistants": [...],
  "total": N
}

预期状态码: 200

验证点:

  • HTTP 状态码为 200
  • 响应时间 < 1 秒 (根据实际数据量调整)

TC-E-014: 深度嵌套的 namespace

测试目的: 测试使用深度嵌套 namespace 的性能

测试类型: 性能测试

curl 命令:

curl -X PUT "$API_BASE_URL/store/items" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "deep-key",
    "namespace": ["level1", "level2", "level3", "level4", "level5"],
    "value": {"data": "test"}
  }' \
  -w "\nHTTP Status: %{http_code}\n"

预期响应:

{
  "status": "stored"
}

预期状态码: 200

验证点:

  • HTTP 状态码为 200

测试执行顺序建议

完整业务流程测试顺序

  1. 健康检查 (TC-H-001 ~ TC-H-005)

    • 验证服务可用性

  2. Assistants CRUD (TC-A-001 ~ TC-A-018)

    • 创建 Assistant
    • 查询 Assistant
    • 更新 Assistant
    • 搜索 Assistant
    • 删除 Assistant

  3. Threads CRUD (TC-T-001 ~ TC-T-010)

    • 创建 Thread
    • 查询 Thread
    • 更新 Thread
    • 搜索 Thread

  4. Runs CRUD (TC-R-001 ~ TC-R-024)

    • 创建 Run
    • 查询 Run
    • 流式执行 Run
    • 取消 Run
    • 删除 Run

  5. Store CRUD (TC-S-001 ~ TC-S-012)

    • 存储数据
    • 查询数据
    • 搜索数据
    • 删除数据

  6. 异常场景测试 (TC-E-001 ~ TC-E-014)

    • 认证测试
    • 输入验证测试
    • 边界条件测试
    • 并发测试
    • 性能测试

快速回归测试顺序

  1. TC-H-001 (健康检查)
  2. TC-A-001 (创建 Assistant)
  3. TC-A-004 (列出 Assistants)
  4. TC-T-001 (创建 Thread)
  5. TC-T-005 (列出 Threads)
  6. TC-R-001 (创建 Run)
  7. TC-R-005 (列出 Runs)
  8. TC-S-001 (存储数据)
  9. TC-S-003 (获取数据)
  10. TC-S-007 (删除数据)

附录

A. 测试数据清理脚本

#!/bin/bash

# 清理测试数据
echo "清理测试数据..."

# 删除测试 Threads
curl -X DELETE "$API_BASE_URL/threads/test-thread-001" \
  -H "Authorization: Bearer $API_TOKEN"

curl -X DELETE "$API_BASE_URL/threads/concurrent-thread-001" \
  -H "Authorization: Bearer $API_TOKEN"

# 删除测试 Assistants
curl -X DELETE "$API_BASE_URL/assistants/test-assistant-001" \
  -H "Authorization: Bearer $API_TOKEN"

echo "清理完成"

B. 测试报告模板

Aegra API 测试报告
===================

测试日期: YYYY-MM-DD
测试环境: http://localhost:8000
测试人员: [姓名]

测试统计
--------
总测试用例数: XX
通过: XX
失败: XX
跳过: XX

测试结果
--------
[测试用例编号] [测试用例名称] [状态]
----------------------------------------
TC-H-001     GET /health - 服务健康检查      PASS
TC-H-002     GET /ready - 就绪状态检查      PASS
...

失败用例详情
------------
[测试用例编号] [失败原因]
----------------------------------------
TC-A-005     响应时间超过预期 (2.5s)
...

问题跟踪
--------
[问题编号] [问题描述] [严重程度]
----------------------------------------
BUG-001     创建 Assistant 时 metadata 未正确添加 owner 字段  High
...

C. 常见问题排查

  1. 401 Unauthorized

    • 检查 Token 是否正确
    • 检查 Token 是否过期

  2. 404 Not Found

    • 确认资源 ID 是否正确
    • 确认资源是否属于当前用户

  3. 409 Conflict

    • 确认资源 ID 是否已存在
    • 使用不同的 ID 或先删除现有资源

  4. 422 Validation Error

    • 检查请求体格式是否正确
    • 检查必需字段是否提供
    • 检查字段值类型是否正确

  5. 500 Internal Server Error

    • 检查服务器日志
    • 确认数据库连接是否正常
    • 确认 LangGraph 服务是否正常运行

文档版本: 1.0 最后更新: 2024-01-01 维护者: Aegra Team

Related Documents

TEST_CASES.md

Тест-кейси для мануального тестування UI

1. [Загальні тест-кейси](#1-загальні-тест-кейси)

ai
0
1
oryshchych
TEST_CASES.md

Comprehensive Test Cases

Test cases for `%TypedArray%.prototype.search`, `%TypedArray%.prototype.searchLast`, and `%TypedArray%.prototype.contains`.

ai
0
1
tc39