mini-starter/docs/stories/005.002.story.md

Story 005.002: 迁移服务器端测试工具

父史诗: 史诗005 - 测试工具包迁移与架构优化 docs/prd/epic-005-test-utils-migration.md

Status

Draft

Story

As a 开发工程师 I want 将服务器端测试工具迁移到共享测试工具包 so that 我可以统一管理服务器测试工具，提高代码复用性和维护性，为后续测试迁移提供基础

Acceptance Criteria

1. 迁移数据库测试工具（integration-test-db.ts, test-db.ts）
2. 迁移认证测试工具（test-auth.ts）
3. 迁移集成测试工具（integration-test-utils.ts）
4. 更新所有导入路径

Tasks / Subtasks

• 验证现有测试工具包结构 (AC: #1, #2, #3)
  • 检查 packages/test-utils/src/server/ 目录结构
  • 验证已迁移的文件内容完整性
  • 确认文件导出和导入路径正确
• 更新测试工具包导出配置 (AC: #4)
  • 更新 packages/test-utils/src/server/index.ts 导出文件
  • 验证所有服务器测试工具正确导出
  • 测试工具包构建和类型检查
• 验证迁移完整性 (AC: #1, #2, #3, #4)
  • 比较原始文件和迁移文件内容
  • 验证所有功能保持完整
  • 确认无导入路径错误
• 更新项目导入路径 (AC: #4)
  • 查找所有使用原测试工具的文件
  • 更新导入路径到 @d8d/test-utils
  • 验证类型检查和构建通过
• 测试迁移后的工具 (AC: #1, #2, #3, #4)
  • 运行相关测试验证工具功能
  • 验证集成测试继续正常工作
  • 确认无回归问题

Dev Notes

技术栈和包管理 [Source: architecture/tech-stack.md#现有技术栈维护]

• 运行时: Node.js 20.18.3，支持ES模块
• 包管理器: pnpm workspace 管理多包依赖关系
• 构建工具: TypeScript 编译，支持严格模式
• 测试框架: Vitest 2.x，与现有测试策略保持一致

项目结构指导 [Source: architecture/source-tree.md#实际项目结构]

• 包位置: packages/test-utils 与其他共享包并列
• 服务器测试工具位置: packages/test-utils/src/server/
• 目录结构:
  • integration-test-db.ts - 集成测试数据库工具
  • test-db.ts - 数据库测试工具
  • test-auth.ts - 认证测试工具
  • integration-test-utils.ts - 集成测试工具函数
• 导入路径: 使用 @d8d/test-utils 命名空间导入

现有测试工具分析 [Source: 现有代码分析]

• integration-test-db.ts: 集成测试数据库工具类，使用真实PostgreSQL数据库
  • IntegrationTestDatabase - 数据库生命周期管理
  • TestDataFactory - 测试数据工厂
  • setupIntegrationDatabaseHooks - 测试钩子设置
• test-db.ts: 单元测试数据库工具，使用模拟数据库
  • createMockDataSource - 模拟数据源
  • createMockRepository - 模拟Repository
  • TestDatabase - SQLite内存数据库测试工具
• test-auth.ts: 认证测试工具
  • createMockAuthContext - 模拟认证上下文
  • createMockJwtPayload - 模拟JWT载荷
  • createMockAuthMiddleware - 模拟认证中间件
• integration-test-utils.ts: 集成测试断言工具
  • IntegrationTestAssertions - 集成测试断言类

编码标准要求 [Source: architecture/coding-standards.md#增强特定标准]

• 代码风格: TypeScript严格模式，一致的缩进和命名
• 测试位置: tests/ 文件夹与源码并列
• 覆盖率目标: 核心工具函数 > 80%
• 导出约定: 使用命名导出，避免默认导出

测试策略要求 [Source: architecture/testing-strategy.md#测试金字塔策略]

• 单元测试: 位于 tests/unit/，验证独立工具函数
• 集成测试: 位于 tests/integration/，验证工具组合使用
• 测试框架: Vitest 2.x，与项目其他部分保持一致
• 覆盖率要求: 工具包核心函数 ≥ 80%

包依赖关系 [Source: 现有项目分析]

• 运行时依赖: 与现有项目技术栈保持一致
• 开发依赖: 包含必要的测试和构建工具
• peer依赖: 可能需要声明对核心框架的依赖
• workspace依赖: 通过 pnpm workspace 管理内部包依赖

项目结构对齐说明

• 符合架构: 新的 packages/test-utils 结构与现有的 packages/server 保持一致
• 目录约定: 遵循 monorepo 标准的包目录结构
• 构建流程: 与现有构建工具链集成
• 导入路径: 使用 workspace 别名导入

Testing

测试策略

• 测试类型: 验证迁移后的测试工具功能
• 测试范围: 数据库工具、认证工具、集成测试工具
• 验证点:
  • 所有工具函数正常工作
  • 导入路径解析正确
  • 类型检查通过
  • 构建流程无错误

测试用例

• 验证数据库测试工具创建和清理功能
• 验证认证工具模拟上下文功能
• 验证集成测试断言工具功能
• 验证所有导入路径正确解析

Change Log

Date	Version	Description	Author
2025-11-09	1.0	初始故事创建	Bob (SM)

Dev Agent Record

Agent Model Used

Debug Log References

Completion Notes List

File List