epic-005-test-utils-migration.md 4.1 KB
测试工具包迁移与架构优化 - Brownfield Epic
Epic Goal
将现有测试工具和集成测试从web项目迁移到独立的共享测试工具包，优化monorepo架构的测试组织，提高代码复用性和维护性。
Epic Description
现有系统上下文
- 当前状态：测试工具和集成测试分散在web项目中，存在代码重复和维护困难
- 技术栈：Node.js + TypeScript + Hono + PostgreSQL + Vitest + React
- 集成点：数据库测试工具、认证测试工具、API测试客户端、React测试工具
- 现有测试：✅ 服务器集成测试、前端组件测试、API测试
迁移详情
- 目标架构：创建独立的
@d8d/test-utils包，统一管理所有测试工具 - 迁移范围：
- 服务器集成测试工具（数据库、认证、API客户端）
- 前端测试工具（React组件、路由、状态管理）
- 集成测试文件从web迁移到packages/server
- 架构优化：
- 清晰的包边界和依赖关系
- 统一的测试工具接口
- 更好的代码复用和类型安全
Stories
Story 005.001: 创建共享测试工具包基础设施
- 创建
packages/test-utils目录结构 - 配置package.json和TypeScript配置
- 建立基础导出接口
- 配置workspace依赖
- 创建
Story 005.002: 迁移服务器端测试工具
- 迁移数据库测试工具（integration-test-db.ts, test-db.ts）
- 迁移认证测试工具（test-auth.ts）
- 迁移集成测试工具（integration-test-utils.ts）
- 更新所有导入路径
Story 005.003: 迁移客户端测试工具
- 迁移React查询测试工具（test-query.tsx）
- 迁移React渲染测试工具（test-render.tsx）
- 迁移路由测试工具（test-router.tsx）
- 更新前端测试导入
Story 005.004: 配置packages/server测试环境
- 创建vitest配置
- 设置测试环境setup
- 更新package.json测试脚本
- 验证测试环境
Story 005.005: 迁移服务器集成测试
- 创建目标目录结构
- 迁移认证集成测试
- 迁移备份集成测试
- 迁移文件管理集成测试
- 迁移用户管理集成测试
- 更新所有测试导入
Story 005.006: 更新根项目配置
- 更新workspace配置
- 调整根vitest配置
- 更新web项目依赖
- 验证CI/CD流程
Story 005.007: 验证和清理
- 运行所有迁移后的测试
- 清理原web项目中的测试文件
- 更新文档和README
- 性能基准测试
兼容性要求
- 现有测试功能保持不变
- 测试执行结果一致
- 开发体验无退化
- CI/CD流程继续正常工作
- 类型安全得到保持
风险缓解
- 主要风险：导入路径错误导致测试失败
- 缓解措施：使用TypeScript严格检查，逐步迁移验证
- 次要风险：工具包接口不兼容
- 缓解措施：保持向后兼容的接口设计
- 回滚计划：恢复原测试文件，移除测试工具包
完成定义
- 所有测试工具成功迁移到共享包
- 服务器集成测试在packages/server中正常运行
- 前端测试继续正常工作
- 无重复代码或工具类
- 导入路径全部正确
- CI/CD流程无错误
验证检查清单
范围验证
- Epic目标清晰可实现
- 故事范围适当
- 迁移计划完整
- 集成复杂度可控
风险评估
- 对现有系统风险可控
- 回滚计划可行
- 测试覆盖现有功能
- 团队具备迁移知识
完整性检查
- Epic目标清晰可实现
- 故事范围适当
- 成功标准可衡量
- 依赖项已识别
时间估算
- Story 005.001: 2-3小时
- Story 005.002: 2-3小时
- Story 005.003: 1-2小时
- Story 005.004: 1-2小时
- Story 005.005: 3-4小时
- Story 005.006: 1-2小时
- Story 005.007: 1-2小时
总计：11-18小时
后续优化建议
- 考虑将单元测试也迁移到对应的包中
- 创建统一的测试运行脚本
- 添加测试覆盖率报告
- 优化测试数据管理
- 建立测试工具包版本管理