mini-starter/docs/stories/005.001.server-test-environment.md

Story 005.001: 为packages/server配置测试环境

父史诗: 史诗005 - Server测试迁移优化 docs/prd/epic-005-server-test-migration.md

Status

Ready for Review

Story

As a 开发工程师 I want 为packages/server配置完整的测试环境 so that 我可以在独立的服务器包中运行单元测试和集成测试，使packages/server成为一个真正独立的、可测试的库包

Acceptance Criteria

1. 在packages/server/package.json中添加测试脚本
2. 创建packages/server/vitest.config.ts配置文件
3. 建立packages/server/tests目录结构
4. 配置测试依赖和工具

Tasks / Subtasks

• 在packages/server/package.json中添加测试脚本 (AC: 1)
  • 添加test脚本运行所有测试
  • 添加test:unit脚本运行单元测试
  • 添加test:integration脚本运行集成测试
  • 添加test:coverage脚本生成覆盖率报告
  • 添加test:typecheck脚本进行类型检查
• 创建packages/server/vitest.config.ts配置文件 (AC: 2)
  • 配置Node.js测试环境
  • 设置测试别名映射
  • 配置覆盖率报告
  • 设置测试超时和排除规则
• 建立packages/server/tests目录结构 (AC: 3)
  • 创建tests/unit目录用于单元测试
  • 创建tests/integration目录用于集成测试
  • 创建tests/utils目录用于测试工具
  • 创建tests/fixtures目录用于测试数据
• 配置测试依赖和工具 (AC: 4)
  • 添加vitest和测试相关依赖到devDependencies
  • 配置测试数据库连接
  • 创建测试设置文件
  • 复制web/tests/utils/server目录下的测试工具
  • 验证测试环境正常工作

Dev Notes

技术栈信息

• 测试框架: Vitest 3.2.4 [Source: architecture/tech-stack.md#新技术添加]
• Node.js版本: 20.18.3 [Source: architecture/tech-stack.md#现有技术栈维护]
• TypeScript: 5.8.3 [Source: architecture/tech-stack.md#现有技术栈维护]

项目结构信息

• packages/server位置: /packages/server/ [Source: architecture/source-tree.md#实际项目结构]
• 测试目录结构:
  • tests/unit/ - 单元测试
  • tests/integration/ - 集成测试
  • tests/utils/ - 测试工具
  • tests/fixtures/ - 测试数据 [Source: architecture/source-tree.md#实际项目结构]
• 现有web测试参考: /web/tests/ 目录结构可作为参考 [Source: architecture/source-tree.md#实际项目结构]

编码标准和测试策略

• 测试文件位置: __tests__ 文件夹与源码并列 [Source: architecture/coding-standards.md#增强特定标准]
• 测试类型: 单元测试、集成测试、E2E测试 [Source: architecture/coding-standards.md#增强特定标准]
• 覆盖率目标: 核心业务逻辑 > 80% [Source: architecture/coding-standards.md#增强特定标准]

测试策略要求

• 单元测试范围: 单个函数、类或组件 [Source: architecture/testing-strategy.md#单元测试-unit-tests]
• 集成测试范围: 多个组件/服务协作 [Source: architecture/testing-strategy.md#集成测试-integration-tests]
• 测试位置: tests/unit/**/*.test.{ts,tsx} 和 tests/integration/**/*.test.{ts,tsx} [Source: architecture/testing-strategy.md#单元测试-unit-tests]
• 覆盖率目标: 单元测试 ≥ 80%，集成测试 ≥ 60% [Source: architecture/testing-strategy.md#各层覆盖率要求]

现有配置参考

• web/vitest.config.ts: 现有的web测试配置可作为参考
• web/package.json: 现有的测试脚本配置可作为参考
• web/tests/utils/server/: 现有的测试工具目录，包含以下重要文件：
  • integration-test-db.ts - 集成测试数据库工具，使用真实PostgreSQL数据库
  • integration-test-utils.ts - 集成测试断言工具

项目结构注意事项

• packages/server目前没有测试配置和测试文件
• 需要创建与web目录类似的测试目录结构
• 测试配置需要针对纯Node.js环境（无前端组件测试）
• web/tests/utils/server目录下的测试工具需要复制到packages/server/tests/utils/目录

Testing

测试标准

• 测试框架: Vitest [Source: architecture/testing-strategy.md#测试框架]
• 测试位置: tests/unit/ 和 tests/integration/ [Source: architecture/testing-strategy.md#测试位置]
• 测试文件命名: [module].test.ts 或 [module].integration.test.ts [Source: architecture/testing-strategy.md#测试命名约定]
• 测试描述: 使用「应该...」格式描述测试行为 [Source: architecture/testing-strategy.md#测试命名约定]

测试环境配置

• 环境: Node.js [Source: architecture/testing-strategy.md#开发环境]
• 别名映射: 配置 @ 指向 src 目录 [参考 web/vitest.config.ts]
• 覆盖率: 使用v8提供者，生成text、lcov、html报告 [参考 web/vitest.config.ts]

测试依赖要求

• 核心依赖: vitest, @vitest/coverage-v8
• 测试工具: hono/testing (用于API测试)
• 类型定义: @types/node (已存在)

测试工具要求

• 数据库测试工具: 需要复制web/tests/utils/server目录下的数据库测试工具
  • integration-test-db.ts - 集成测试真实数据库工具
• 测试断言工具: 需要复制集成测试断言工具
  • integration-test-utils.ts - 响应状态码、数据结构等断言工具

Change Log

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

Dev Agent Record

Agent Model Used

Debug Log References

Completion Notes List

• ✅ packages/server/package.json 已包含完整的测试脚本配置
• ✅ packages/server/vitest.config.ts 已配置完整的测试环境
• ✅ packages/server/tests 目录结构已建立
• ✅ 测试工具文件已从 web/tests/utils/server 复制到 packages/server/tests/utils
• ✅ 更新了 packages/server/tsconfig.json，将 rootDir 改为 "." 并包含 tests 目录
• ✅ 修复了测试工具文件中的导入路径问题
• ✅ 测试环境验证通过，所有测试和类型检查正常运行
• ⚠️ 故事中提到的 test-db.ts、test-auth.ts、service-mocks.ts、service-stubs.ts 文件实际不存在，已确认只有 integration-test-db.ts 和 integration-test-utils.ts 两个文件

File List

• packages/server/package.json - 测试脚本配置
• packages/server/vitest.config.ts - Vitest 配置
• packages/server/tsconfig.json - TypeScript配置（已更新包含tests目录）
• packages/server/tests/unit/example.test.ts - 示例单元测试
• packages/server/tests/utils/setup.ts - 测试设置文件
• packages/server/tests/utils/integration-test-db.ts - 集成测试数据库工具
• packages/server/tests/utils/integration-test-utils.ts - 集成测试断言工具

QA Results