PUAX MCP Server 测试用例文档

PUAX MCP Server 测试用例文档

概述

本文档详细描述了 puax-mcp-server 的测试用例，覆盖了从单元测试到集成测试的各个层面。

测试结构

test/
├── setup.js                      # 测试环境配置
├── sequencer.js                  # 测试序列器
├── unit/                         # 单元测试
│   └── server.test.js           # 服务器单元测试
├── http/                         # HTTP 端点测试
│   └── endpoint.test.js         # HTTP 端点功能测试
├── sse/                          # SSE 传输测试
│   └── transport.test.js        # Server-Sent Events 测试
├── tools/                        # 工具功能测试
│   └── tools.test.js            # MCP 工具测试
└── integration/                  # 集成测试
    └── mcp-flow.test.js         # 完整流程测试

测试分类

1. 单元测试 (Unit Tests)

文件: test/unit/server.test.js

1.1 构造函数测试

  • ✅ 应该正确创建服务器实例
  • ✅ 应该初始化 transports Map

1.2 工具处理器设置测试

  • ✅ 应该设置 ListTools 处理器
  • ✅ 应该设置 CallTool 处理器

1.3 HTTP 服务器创建测试

  • ✅ 应该创建 HTTP 服务器
  • ✅ 应该监听 23333 端口

1.4 健康检查端点测试

  • ✅ 应该返回健康状态
  • ✅ 应该包含正确的状态信息

1.5 错误处理测试

  • ✅ 应该返回 404 对于未知路径
  • ✅ 应该返回 405 对于不支持的 HTTP 方法

2. HTTP 端点测试

文件: test/http/endpoint.test.js

2.1 SSE 连接端点 (GET /)

  • ✅ 应该接受 SSE 连接
  • ✅ 应该发送正确的 SSE 头信息
  • ✅ 应该返回 endpoint 事件
  • ✅ 应该生成唯一的 sessionId
  • ✅ 应该支持多个并发连接

2.2 消息端点 (POST /message)

  • ✅ 应该拒绝没有 sessionId 的请求（400）
  • ✅ 应该拒绝无效的 sessionId（404）

2.3 健康检查端点 (GET /health)

  • ✅ 应该返回正确的健康状态
  • ✅ 应该包含服务信息
  • ✅ 应该反映正确的活跃会话数

2.4 错误处理

  • ✅ 应该返回 404 对于未知路径
  • ✅ 应该返回 404/405 对于不支持的 HTTP 方法

2.5 并发请求处理

  • ✅ 应该同时处理多个健康检查请求

3. SSE 传输测试

文件: test/sse/transport.test.js

3.1 SSE 连接生命周期

  • ✅ 应该完成完整的连接握手
  • ✅ 应该设置正确的响应头
  • ✅ 应该保持连接直到客户端关闭
  • ✅ 应该处理多个并发的 SSE 连接
  • ✅ 每个连接应该有唯一的 sessionId

3.2 SSE 消息格式

  • ✅ 应该发送正确格式的 SSE 事件
  • ✅ 应该包含 event 和 data 字段
  • ✅ 应该对数据进行 URI 编码

3.3 SSE 连接管理

  • ✅ 应该在连接关闭时清理资源
  • ✅ 应该处理意外的客户端断开
  • ✅ 不应该导致服务器崩溃

3.4 SSE + HTTP POST 组合

  • ✅ 应该允许消息发送到有效的 SSE 会话
  • ✅ 应该拒绝发送到无效会话的消息

4. 工具功能测试

文件: test/tools/tools.test.js

4.1 list_roles 工具

  • ✅ 应该列出所有角色（默认分类）
  • ✅ 应该按分类筛选角色
  • ✅ 返回的数据应该包含正确的字段
  • ✅ 返回的角色应该属于指定的分类

4.2 get_role 工具

  • ✅ 应该获取指定角色的详细信息
  • ✅ 应该包含角色元数据和内容
  • ✅ 应该替换任务占位符
  • ✅ 应该处理不存在的角色
  • ✅ 应该验证必需参数

4.3 search_roles 工具

  • ✅ 应该搜索到匹配的角色
  • ✅ 应该返回空结果当没有匹配时
  • ✅ 搜索结果应该包含关键词
  • ✅ 应该处理空关键词

4.4 activate_role 工具

  • ✅ 应该激活角色并返回 System Prompt
  • ✅ 应该包含角色信息
  • ✅ 应该包含任务描述
  • ✅ 应该处理自定义参数
  • ✅ 应该处理不存在的角色
  • ✅ 应该验证必需参数

4.5 边界情况

  • ✅ 应该处理缺少必需参数
  • ✅ 应该处理不存在的工具
  • ✅ 应该处理无效的参数类型
  • ✅ 应该处理大型请求负载

5. 集成测试

文件: test/integration/mcp-flow.test.js

5.1 完整工作流程

  • ✅ 步骤 1: 健康检查
  • ✅ 步骤 2: 建立 SSE 连接
  • ✅ 步骤 3: 列出工具
  • ✅ 步骤 4: 调用工具 (list_roles)
  • ✅ 步骤 5: 验证结果
  • ✅ 所有步骤应该连贯执行

5.2 多会话支持

  • ✅ 应该支持多个独立的客户端会话
  • ✅ 每个会话应该有唯一的 sessionId
  • ✅ 会话之间不应该互相干扰
  • ✅ 所有会话应该可以独立使用

5.3 错误场景

  • ✅ 应该处理无效的工具调用
  • ✅ 应该处理工具参数错误
  • ✅ 应该处理无效的 JSON-RPC 格式
  • ✅ 错误不应该导致服务器崩溃

5.4 性能测试

  • ✅ 应该快速处理多个并发请求
  • ✅ 10个并发请求应该在5秒内完成
  • ✅ 所有并发请求都应该成功

测试执行

安装测试依赖

npm install --save-dev jest @types/jest

运行所有测试

# 方式 1: 使用 npm test
npm test

# 方式 2: 使用测试运行器
node run-tests.js all

运行特定测试

# 单元测试
npm run test:unit
node run-tests.js unit

# HTTP 测试
npm run test:http
node run-tests.js http

# SSE 测试
npm run test:sse
node run-tests.js sse

# 工具测试
npm run test:tools
node run-tests.js tools

# 集成测试
npm run test:integration
node run-tests.js integration

# 覆盖率测试
npm run test:coverage
node run-tests.js coverage

监听模式（开发）

npm run test:watch
node run-tests.js watch

冒烟测试（快速验证）

node run-tests.js smoke

CI/CD 模式

npm run test:ci
node run-tests.js ci

覆盖率报告

运行覆盖率测试后，报告会生成在 coverage/ 目录：

npm run test:coverage

查看 HTML 报告：

open coverage/index.html  # macOS
xdg-open coverage/index.html  # Linux
start coverage/index.html  # Windows

测试配置

Jest 配置 (jest.config.js)

  • 测试环境: Node.js
  • 超时时间: 20秒（集成测试需要）
  • 覆盖率阈值: 60%（可调整）
  • 测试顺序: 单元测试 → HTTP测试 → SSE测试 → 工具测试 → 集成测试

测试环境 (test/setup.js)

  • 设置全局变量
  • 提供辅助函数（wait、retry、checkServer）
  • 配置测试环境变量

辅助函数

testHelpers.wait(ms)

等待指定毫秒数

await testHelpers.wait(1000); // 等待1秒

testHelpers.retry(fn, maxAttempts, delay)

重试异步操作

await testHelpers.retry(async () => {
    // 可能失败的操作
}, 3, 1000);

testHelpers.checkServer(url, timeout)

检查服务器是否运行

const isRunning = await testHelpers.checkServer('http://localhost:23333/health');

测试最佳实践

1. 独立性

  • 每个测试应该独立运行
  • 不依赖其他测试的结果
  • 使用 beforeEach/afterEach 清理状态

2. 可重复性

  • 测试应该可以重复执行
  • 产生相同的结果
  • 不依赖外部状态

3. 快速性

  • 单元测试应该快速完成
  • 使用适当的超时设置
  • 避免不必要的等待

4. 完整性

  • 覆盖正常流程
  • 覆盖错误处理
  • 覆盖边界情况

5. 可读性

  • 清晰的测试描述
  • 合理的组织结构
  • 适当的注释

持续集成

GitHub Actions 示例

name: Run Tests

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    
    steps:
    - uses: actions/checkout@v3
    
    - name: Setup Node.js
      uses: actions/setup-node@v3
      with:
        node-version: '18'
    
    - name: Install dependencies
      run: npm install
    
    - name: Build
      run: npm run build
    
    - name: Run tests
      run: npm run test:ci
    
    - name: Upload coverage
      uses: codecov/codecov-action@v3
      with:
        file: ./coverage/lcov.info

常见问题

Q: 测试超时怎么办？

A: 增加超时时间或检查服务器是否正常运行：

jest.setTimeout(30000); // 增加到30秒

Q: 端口被占用怎么办？

A: 停止占用端口的进程或修改测试端口：

# Windows
netstat -ano | findstr :23333
taskkill /PID <pid> /F

# Linux/Mac
lsof -i :23333
kill -9 <pid>

Q: 如何提高测试速度？

A:

  • 使用 --maxWorkers 限制并行测试
  • 将集成测试和单元测试分开运行
  • 使用 --testNamePattern 运行特定测试
npm test -- --maxWorkers=2
npm test -- --testNamePattern="should list"

总结

本测试套件提供了全面的测试覆盖：

  • 测试文件: 6个
  • 测试用例: 50+
  • 测试类别: 5类（单元、HTTP、SSE、工具、集成）
  • 预期覆盖率: >60%

测试覆盖了：

  • ✅ 正常流程
  • ✅ 错误处理
  • ✅ 边界情况
  • ✅ 并发场景
  • ✅ 性能要求

所有测试都可以自动化运行，适合 CI/CD 集成。

文档版本: 1.0.0 最后更新: 2026-01-02 适用版本: puax-mcp-server v1.1.0 (HTTP)

← 返回目录