Neura Market
Back to .md Directory
TEST_CASES.md

Aegra API 测试用例集

Provides 50+ curl-based API test cases for the Aegra Agent Protocol Server covering health, assistants, threads, runs, and store modules.

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

What this file does

Provides 50+ curl-based API test cases for the Aegra Agent Protocol Server covering health, assistants, threads, runs, and store modules.

When to use it

  • You need to manually verify an Aegra API server is working correctly
  • You want a reference for writing automated integration tests against the Aegra API
  • You are onboarding to the Aegra project and need to understand endpoint behaviour

Assumes this stack

curlJSONBash

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

What's inside

7 test groups, 50+ test cases, each with curl command, expected response, status code, and verification checkboxes

Change this for your project

  • Replace http://localhost:8000 with your server's base URL
  • Replace test_user@example.com with your test user's email
  • Replace your_bearer_token_here with a valid API token
  • Replace test-assistant-001 and test-thread-001 with IDs that do not conflict with existing data

Where it goes

Keep it in your repository where the agent or team that needs it will read it.

Worth borrowing

  • Checkbox-based verification points make manual testing systematic and auditable
  • Dependency chaining between test cases (e.g. saving IDs for later use) mirrors real API workflows
  • Separating positive and negative tests per endpoint covers both happy path and error handling

Related Documents

TEST_CASES.md

Comprehensive Test Cases

Lists 200+ test cases for TypedArray.prototype.search, searchLast, and contains, covering validation, matching, edge cases, and semantics.

ai
0
1
tc39
TEST_CASES.md

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

Defines 70+ manual UI test cases for event registration, payment, promo codes, responsive design, and error handling.

ai
0
1
oryshchych