E2E_TEST_GUIDE.md•9.7 kB
# E2E通信链路测试指南
## 📋 测试目的
验证完整的通信链路: **Office Add-in → Bridge Server → MCP Server** 能够正常工作。
## 🏗️ 架构概览
```
┌─────────────────┐ HTTP/WS ┌─────────────────┐ stdio ┌─────────────────┐
│ Office Add-in │ ─────────────────▶│ Bridge Server │ ────────────────▶│ MCP Server │
│ (React/TS) │◀───────────────── │ (Node.js) │◀──────────────── │ (Python) │
└─────────────────┘ JSON Response └─────────────────┘ JSON-RPC 2.0 └─────────────────┘
localhost:3000 localhost:3001 stdio process
```
## 🔧 前提条件
### 1. 所有服务已安装依赖
```bash
# MCP Server
pip install -r requirements.txt
# Bridge Server
cd bridge-server && npm install
# Office Add-in (可选,用于前端测试)
cd office-addin && npm install
```
### 2. 环境配置
确保 `.env` 文件存在:
```bash
# 检查环境配置
cat .env.example
```
必要配置项:
- `LOG_TO_FILE=true`
- `LOG_LEVEL=INFO`
- `PYTHON_PATH`: Python可执行文件路径
- `MCP_SERVER_PATH`: MCP服务器入口文件路径
## 🚀 测试步骤
### 第一步: 启动MCP Server
```bash
# 方法1: 使用批处理脚本(推荐)
start_mcp_server.bat
# 方法2: 直接启动
venv\Scripts\python src\office_mcp_server\main.py
```
**验证MCP Server启动**:
- ✅ 控制台输出: "启动 office-mcp-server v1.0.0"
- ✅ 显示184个工具注册成功
- ✅ 无错误信息
- ✅ 日志文件创建: `logs/office_mcp_server.log`
**等待时间**: 5-10秒
### 第二步: 启动Bridge Server
```bash
# 方法1: 使用批处理脚本(推荐)
start_bridge_server.bat
# 方法2: 直接启动
cd bridge-server && npm run dev
```
**验证Bridge Server启动**:
- ✅ 控制台输出: "Bridge Server运行在 http://localhost:3001"
- ✅ MCP Client连接成功
- ✅ 获取到服务器信息
- ✅ 无连接错误
**等待时间**: 10-15秒(包含MCP Client初始化)
**常见启动日志**:
```
[INFO]: 启动MCP服务器: python src/office_mcp_server/main.py
[INFO]: MCP服务器初始化成功
[INFO]: Bridge Server运行在 http://localhost:3001
```
### 第三步: 手动测试API端点
#### 测试1: 健康检查
**命令**:
```bash
curl http://localhost:3001/api/health
```
**预期响应**:
```json
{
"status": "healthy",
"timestamp": "2025-01-13T10:30:45.123Z",
"uptime": 12.345
}
```
**响应时间**: < 100ms
#### 测试2: 获取服务器信息
**命令**:
```bash
curl http://localhost:3001/api/server/info
```
**预期响应**:
```json
{
"name": "office-mcp-server",
"version": "1.0.0",
"capabilities": {
"tools": true,
"resources": false
}
}
```
**响应时间**: < 1秒
#### 测试3: 获取工具列表
**命令**:
```bash
curl http://localhost:3001/api/tools/list
```
**预期响应**:
```json
{
"tools": [
{
"name": "get_server_info",
"description": "获取MCP服务器信息",
"inputSchema": {...}
},
...184个工具
]
}
```
**验证点**:
- ✅ 返回的工具数量 = 184
- ✅ 每个工具包含name、description、inputSchema
- ✅ 响应时间 < 1秒
#### 测试4: 调用MCP工具
**命令**:
```bash
curl -X POST http://localhost:3001/api/tools/call \
-H "Content-Type: application/json" \
-d "{\"tool\": \"get_server_info\", \"parameters\": {}}"
```
**预期响应**:
```json
{
"content": [
{
"type": "text",
"text": "服务器信息: office-mcp-server v1.0.0, 已注册184个工具"
}
]
}
```
**验证点**:
- ✅ 工具调用成功
- ✅ 返回正确的内容格式
- ✅ 响应时间 < 2秒
### 第四步: 运行自动化E2E测试
```bash
# 方法1: 使用批处理脚本(推荐)
run_e2e_test.bat
# 方法2: 直接运行
node tests\e2e\bridge-communication.test.js
```
**预期输出**:
```
开始E2E测试...
✓ 测试1: 健康检查 (45ms)
✓ 测试2: 获取服务器信息 (892ms)
✓ 测试3: 获取工具列表 (756ms)
✓ 测试4: 调用get_server_info工具 (1234ms)
✓ 测试5: 响应时间测试 (89ms)
✓ 测试6: 错误处理测试 (124ms)
✓ 测试7: 404处理 (56ms)
测试完成! 通过: 7/7 失败: 0/7
```
**测试报告**: 保存在 `tests/results/e2e-test-{timestamp}.json`
### 第五步: 性能基准测试(可选)
```bash
# 方法1: 使用批处理脚本
run_performance_test.bat
# 方法2: 直接运行
node tests\e2e\performance-benchmark.test.js
```
**预期输出**:
```
性能基准测试
============
1. 健康检查延迟测试 (100次请求)
平均延迟: 45.2ms
中位数: 42ms
P95: 78ms
P99: 120ms
2. 工具调用延迟测试 (50次请求)
平均延迟: 890ms
中位数: 856ms
P95: 1245ms
P99: 1678ms
3. 并发性能测试 (10并发 x 10请求)
总请求数: 100
成功数: 100
失败数: 0
总耗时: 2.5s
吞吐量: 40 req/s
性能测试完成!
```
**性能指标目标**:
- 健康检查平均延迟: < 100ms ✅
- P95延迟: < 200ms ✅
- MCP工具调用: < 2秒 ✅
- 并发吞吐量: > 30 req/s ✅
## 📊 测试检查清单
### 服务启动检查
- [ ] MCP Server成功启动
- [ ] Bridge Server成功启动
- [ ] MCP Client初始化成功
- [ ] 无启动错误
### API端点检查
- [ ] `/api/health` 返回200
- [ ] `/api/server/info` 返回服务器信息
- [ ] `/api/tools/list` 返回184个工具
- [ ] `/api/tools/call` 成功调用工具
### E2E测试检查
- [ ] 7个测试用例全部通过
- [ ] 无测试失败
- [ ] 响应时间符合预期
- [ ] 测试报告生成
### 性能测试检查
- [ ] 健康检查延迟 < 100ms
- [ ] P95延迟 < 200ms
- [ ] 工具调用 < 2秒
- [ ] 吞吐量 > 30 req/s
## 🎯 成功标准
E2E通信链路测试通过的标准:
1. ✅ **服务稳定启动**: 三个服务(MCP、Bridge、Add-in)都能成功启动
2. ✅ **端点可达性**: 所有API端点返回正确响应
3. ✅ **工具调用成功**: MCP工具能够被正确调用并返回结果
4. ✅ **测试覆盖率**: E2E测试7/7通过
5. ✅ **性能达标**: 响应时间和吞吐量符合目标
6. ✅ **错误处理**: 错误场景能够正确处理和报告
## 🐛 常见问题排查
### 问题1: MCP Server无法启动
**症状**: Python进程报错或立即退出
**排查步骤**:
1. 检查Python环境:
```bash
venv\Scripts\python --version # 应该是3.12+
```
2. 检查依赖安装:
```bash
pip list | grep fastmcp
```
3. 查看日志:
```bash
type logs\office_mcp_server.log
```
4. 测试手动启动:
```bash
venv\Scripts\python src\office_mcp_server\main.py
```
**常见错误**:
- `ModuleNotFoundError`: 依赖未安装
- `ImportError`: Python版本过低
- `PermissionError`: 日志目录权限问题
### 问题2: Bridge Server连接MCP失败
**症状**: "MCP服务器未初始化"或"MCP请求超时"
**排查步骤**:
1. 确认MCP Server正在运行
2. 检查Bridge Server配置:
```bash
type bridge-server\.env
```
3. 查看Bridge Server日志(控制台输出)
4. 检查进程:
```bash
tasklist | findstr python
tasklist | findstr node
```
**解决方案**:
- 增加MCP Client初始化等待时间(bridge-server/src/services/MCPClient.ts:82)
- 检查stdio通信是否被阻塞
- 重启两个服务
### 问题3: 工具调用返回错误
**症状**: POST `/api/tools/call` 返回500错误
**排查步骤**:
1. 确认工具名称正确:
```bash
curl http://localhost:3001/api/tools/list | grep tool_name
```
2. 检查参数格式:
```json
{
"tool": "tool_name",
"parameters": {} // 必须是对象
}
```
3. 查看MCP Server日志:
```bash
type logs\office_mcp_server.log | findstr ERROR
```
### 问题4: E2E测试超时
**症状**: 测试运行缓慢或超时
**排查步骤**:
1. 检查服务是否运行
2. 增加测试超时时间(tests/e2e/bridge-communication.test.js)
3. 检查网络连接
4. 检查系统资源占用
**解决方案**:
- 关闭其他占用资源的程序
- 重启服务
- 清理临时文件
## 📝 测试报告模板
### 测试环境
- 操作系统: Windows 11
- Node.js版本: v18.19.0
- Python版本: 3.12.5
- 测试日期: 2025-01-13
### 服务启动情况
| 服务 | 状态 | 启动时间 | 端口 | 备注 |
|------|------|---------|------|------|
| MCP Server | ✅ 正常 | 5s | stdio | 184工具注册 |
| Bridge Server | ✅ 正常 | 15s | 3001 | MCP连接成功 |
### API测试结果
| API端点 | 状态码 | 响应时间 | 结果 |
|---------|--------|---------|------|
| /api/health | 200 | 45ms | ✅ |
| /api/server/info | 200 | 892ms | ✅ |
| /api/tools/list | 200 | 756ms | ✅ |
| /api/tools/call | 200 | 1234ms | ✅ |
### E2E测试结果
- 总测试数: 7
- 通过数: 7
- 失败数: 0
- 通过率: 100%
- 总耗时: 3.2秒
### 性能测试结果
| 指标 | 实际值 | 目标值 | 状态 |
|------|--------|--------|------|
| 健康检查平均延迟 | 45ms | <100ms | ✅ |
| P95延迟 | 78ms | <200ms | ✅ |
| 工具调用延迟 | 890ms | <2s | ✅ |
| 并发吞吐量 | 40 req/s | >30 req/s | ✅ |
### 结论
✅ E2E通信链路测试全部通过,系统满足周期1验收标准。
## 📚 参考资料
- [测试文档](tests/README.md)
- [Bridge Server API文档](bridge-server/README.md)
- [MCP协议规范](https://spec.modelcontextprotocol.io/)