ZenTao MCP Server

# 禅道 MCP 服务器测试文档 ## 📋 概述 本文档描述了禅道 MCP 服务器的完整测试体系，包括单元测试、集成测试、性能测试和端到端测试。 **最新测试报告**: 参见项目根目录的 `TEST-REPORTS.md` ## 🏗️ 测试架构 ### 测试框架 - **测试运行器**: Jest - **测试环境**: Node.js - **覆盖率工具**: Jest Coverage - **辅助库**: ts-jest (TypeScript 支持) ### 测试统计 - **测试套件总数**: 15 - **测试用例总数**: 31 - **通过用例**: 26 (83.9%) - **失败用例**: 5 (16.1%) --- ## 📊 测试分类 ### 1. 启动测试 (`tests/startup.test.ts`) **目的**: 验证服务器启动流程和配置 **通过率**: 13/15 (86.7%) **覆盖场景**: - ✅ 构建产物验证 - ✅ 配置文件检查 - ✅ 服务器启动流程 - ✅ 环境变量验证 - ✅ 连接测试（部分通过） ### 2. Token 测试 (`tests/token/*.test.ts`) **目的**: 验证 Token 获取和验证机制 **状态**: ⚠️ 需要有效的 Token 才能运行 **覆盖场景**: - ✅ Token 格式验证 - ✅ Token 有效性检查 - ✅ Token 更新流程 - ✅ 无效 Token 处理 - ✅ Token 过期检测 ### 3. MCP 工具测试 (`tests/tools/*.test.ts`) **目的**: 验证每个 MCP 工具的功能 **工具覆盖**: - ✅ **`get_tasks`** - 获取任务列表 (3/3 测试通过) - 获取任务列表 - 状态过滤 - 缓存机制 - ⚠️ **`get_projects`** - 需要有效 Token - ⚠️ **`get_project_by_id`** - 需要有效 Token - ⚠️ **`create_project`** - 需要有效 Token - ⚠️ **`create_task`** - 需要有效 Token - ⚠️ **`update_task_status`** - 需要有效 Token - ⚠️ **`batch_create_tasks`** - 需要有效 Token ### 4. 错误处理测试 (`tests/error-handling/*.test.ts`) **目的**: 验证错误场景处理 **通过率**: 6/6 (100%) **场景覆盖**: - ✅ 网络错误（超时、连接失败） - ✅ API 错误（401、403、404、500） - ✅ 参数验证错误 - ✅ 权限错误 - ✅ 重试机制 ### 5. 性能测试 (`tests/performance/*.test.ts`) **目的**: 验证性能和稳定性 **通过率**: 2/3 (66.7%) **指标覆盖**: - ✅ 缓存命中率 - ✅ 并发处理能力 (20个请求) - ✅ 响应时间对比 - ✅ 缓存大小限制 - ✅ 过期机制 - ✅ 并发安全 ### 6. 集成测试 (`tests/integration/*.test.ts`) **目的**: 验证端到端工作流 **状态**: ⚠️ 需要有效 Token 才能运行 --- ## 🚀 运行测试 ### 安装依赖 ```bash npm install ``` ### 运行所有测试 ```bash # 使用脚本（推荐） bash tests/run-all-tests.sh # 或使用 npm npm test ``` ### 运行特定类型测试 ```bash npm run test:startup # 启动测试 npm run test:token # Token 测试 npm run test:tools # MCP 工具功能测试 npm run test:errors # 错误处理测试 npm run test:performance # 性能测试 npm run test:integration # 集成测试 ``` ### 其他测试命令 ```bash # 监视模式（自动重新运行） npm run test:watch # 生成覆盖率报告 npm run test:coverage # 清理测试结果 npm run test:clean ``` --- ## 📊 测试覆盖率 ### 总体覆盖率 | 指标 | 当前值 | 目标值 | |------|--------|--------| | 语句覆盖率 | 38.06% | 90% | | 分支覆盖率 | 19.14% | 80% | | 函数覆盖率 | 41.50% | 90% | | 行覆盖率 | 38.41% | 90% | ### 按模块分析 #### 高覆盖率模块 (>80%) ``` ✅ src/types/index.ts 100% ✅ src/utils/cache.ts 88.88% ✅ src/utils/logger.ts 68.42% ``` #### 需要改进的模块 (<60%) ``` 🟡 src/tools/getTasks.ts 58.62% 🟡 src/tools/getProjectById.ts 56.25% 🟡 src/client.ts 45.56% 🟡 src/config.ts 27.27% ❌ 其他工具 0-15% ``` --- ## 📁 测试目录结构 ``` tests/ ├── README.md # 本文档 ├── setup.ts # 测试环境设置 ├── run-all-tests.sh # 测试运行脚本 ├── helpers/ │ └── test-data.ts # 测试数据辅助函数 ├── startup.test.ts # 启动测试 ├── token/ # Token 测试 │ └── token.test.ts ├── tools/ # MCP 工具测试 │ ├── get-projects.test.ts │ ├── get-project-by-id.test.ts │ ├── create-project.test.ts │ ├── get-tasks.test.ts ✅ 完全通过 │ ├── create-task.test.ts │ ├── update-task-status.test.ts │ └── batch-create-tasks.test.ts ├── error-handling/ # 错误处理测试 │ ├── network-errors.test.ts │ └── api-errors.test.ts ✅ 完全通过 ├── performance/ # 性能测试 │ ├── cache-performance.test.ts │ └── concurrency-performance.test.ts └── integration/ # 集成测试 └── e2e.test.ts ``` --- ## 🛠️ 测试环境要求 ### 前置条件 1. **禅道服务器** - 运行在 `http://localhost` - 可访问并响应 API 请求 2. **测试账号** - 用户名: `s000001` - 密码: `q1w2E#R$` 3. **Node.js 环境** - Node.js >= 16.0.0 - npm 已安装 4. **项目构建** - 已运行 `npm run build` - `dist/` 目录存在且包含构建文件 ### 环境变量配置 创建 `.env` 文件: ```env ZENDTAO_BASE_URL=http://localhost ZENDTAO_TOKEN=s000001:<zentaosid> ZENDTAO_TIMEOUT=30000 ZENDTAO_RETRY=3 ZENDTAO_RETRY_DELAY=1000 ``` **获取 Token**: 参见项目根目录 `GETTING-TOKEN.md` --- ## 🔧 测试开发指南 ### 创建新测试 1. **确定测试位置** - 单元测试: `tests/tools/` - 集成测试: `tests/integration/` - 性能测试: `tests/performance/` 2. **测试文件命名** - 使用 `*.test.ts` 扩展名 - 例如: `my-feature.test.ts` 3. **基本测试结构** ```typescript describe('My Feature', () => { beforeEach(() => { global.testCache.clear(); }); test('should work correctly', async () => { // Arrange const input = { ... }; // Act const result = await myFunction(global.testClient, global.testCache, input); // Assert expect(result).toBeDefined(); expect(result.isError).toBeFalsy(); // 更多断言... }); test('should handle errors', async () => { // 测试错误场景 }); }); ``` ### 测试最佳实践 1. **使用辅助函数** ```typescript // 生成唯一测试名称 const testName = generateTestName('我的测试'); // 验证项目对象 validateProject(project); // 清理测试数据 await cleanupProject(client, projectId); ``` 2. **测试数据管理** - 使用时间戳确保唯一性 - 测试完成后自动清理 - 避免数据冲突 3. **异步测试** ```typescript // 正确 test('async test', async () => { const result = await asyncFunction(); expect(result).toBeDefined(); }); // 错误 - 没有 await test('wrong async test', () => { asyncFunction(); // 这不会等待！ }); ``` 4. **错误测试** ```typescript test('should throw error', async () => { await expect(myFunction(invalidInput)) .rejects .toThrow('Expected error message'); }); ``` --- ## 🐛 问题排查 ### 常见问题 #### 1. 测试失败: "Token 无效" **原因**: .env 中的 Token 已过期 **解决**: ```bash # 更新 Token bash fetch-token.sh # 验证 Token ./diagnose-token.sh # 重新运行测试 npm run test:startup ``` #### 2. 测试超时 **原因**: API 响应慢或网络问题 **解决**: - 检查禅道服务器状态 - 增加超时时间 (`ZENDTAO_TIMEOUT`) - 重试次数 (`ZENDTAO_RETRY`) #### 3. 构建失败 **原因**: TypeScript 编译错误 **解决**: ```bash # 重新构建 npm run build # 检查类型错误 npm run lint ``` #### 4. 测试数据污染 **原因**: 之前的测试未清理数据 **解决**: ```bash # 清理所有测试数据 npm test -- --runInBand # 串行运行 ``` ### 调试测试 #### 启用详细日志 ```bash # 监视模式 npm run test:watch # 调试特定测试 npm test -- --testNamePattern="测试名称" ``` #### 跳过测试 ```typescript test.skip('skipped test', () => { ... }); // 或 test('conditional test', () => { if (!condition) { console.log('⏭️ Skipping test'); return; } // 测试代码... }); ``` --- ## 📈 持续集成 ### GitHub Actions 配置示例 ```yaml name: Tests on: [push, pull_request] jobs: test: runs-on: ubuntu-latest steps: - uses: actions/checkout@v2 - uses: actions/setup-node@v2 with: node-version: '16' - run: npm install - run: npm run build - run: npm run test:coverage - uses: codecov/codecov-action@v2 with: file: ./coverage/lcov.info ``` --- ## 📝 测试清单 ### 发布前检查 - [ ] 所有测试通过 - [ ] 测试覆盖率 >= 90% - [ ] 没有内存泄漏 - [ ] 性能测试通过 - [ ] 集成测试通过 - [ ] 错误处理正确 - [ ] 文档已更新 ### 新功能测试 - [ ] 单元测试覆盖所有新代码 - [ ] 集成测试覆盖新工作流 - [ ] 错误场景已测试 - [ ] 边界条件已测试 - [ ] 性能影响已评估 --- ## 🤝 贡献指南 ### 提交测试代码 1. 创建测试文件 2. 遵循命名约定 3. 确保测试独立 4. 包含清理逻辑 5. 更新文档 ### 代码审查检查清单 - [ ] 测试覆盖所有代码路径 - [ ] 测试名称清晰描述 - [ ] 断言准确且有用 - [ ] 没有不必要的测试 - [ ] 测试可读性和维护性 --- ## 📚 参考资料 - [Jest 官方文档](https://jestjs.io/docs) - [TypeScript 测试最佳实践](https://typescript-eslint.io/docs/linting/testing-linting) - [禅道 API 文档](https://www.zentao.net/book/zentao_help/book/zentao_api.html) - [MCP 协议规范](https://modelcontextprotocol.io/) --- **维护者**: Claude Code **最后更新**: 2025-11-02 **版本**: v2.0 (更新版)