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

Story 005.001: 创建共享测试工具包基础设施

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

Status

Ready for Review

Story

As a 开发工程师 I want 创建独立的共享测试工具包基础设施 so that 我可以统一管理所有测试工具，提高代码复用性和维护性，为后续测试工具迁移提供基础

Acceptance Criteria

1. 创建 packages/test-utils 目录结构
2. 配置 package.json 和 TypeScript 配置
3. 建立基础导出接口
4. 配置 workspace 依赖

Tasks / Subtasks

• 创建测试工具包目录结构 (AC: #1)
  • 创建 packages/test-utils 基础目录
  • 建立标准的包目录结构：src/, tests/, dist/
  • 创建必要的配置文件目录
• 配置 package.json (AC: #2)
  • 定义包名：@d8d/test-utils
  • 配置版本和描述
  • 定义入口点和类型定义
  • 配置依赖项和开发依赖项
  • 添加测试脚本
• 配置 TypeScript 编译设置 (AC: #2)
  • 创建 tsconfig.json 文件
  • 配置模块解析和输出目标
  • 设置类型检查和编译选项
  • 配置路径映射和别名
• 建立基础导出接口 (AC: #3)
  • 创建主导出文件 src/index.ts
  • 定义测试工具包的基础接口
  • 设置模块导出结构
  • 添加类型定义导出
• 配置 workspace 依赖 (AC: #4)
  • 更新根 package.json 的 workspace 配置
  • 配置其他包对测试工具包的引用依赖，更新tsconfig.json
  • 验证 workspace 依赖关系
  • 测试包导入和构建

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 与其他共享包并列
• 目录结构:
  • src/ - 源代码目录
  • tests/ - 测试文件目录
  • dist/ - 编译输出目录
  • package.json - 包配置
  • tsconfig.json - TypeScript配置
• 命名约定: 包名使用 @d8d/test-utils 命名空间
• 导出结构: 统一的模块导出接口

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

• 服务器测试工具: web/tests/utils/server/
  • integration-test-db.ts - 集成测试数据库工具
  • integration-test-utils.ts - 集成测试工具函数
  • test-auth.ts - 认证测试工具
  • test-db.ts - 数据库测试工具
• 客户端测试工具: web/tests/utils/client/
  • test-query.tsx - React查询测试工具
  • test-render.tsx - React渲染测试工具
  • test-router.tsx - 路由测试工具
• 通用测试工具: web/tests/utils/test-utils.ts

编码标准要求 [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

测试策略

• 测试类型: 单元测试验证工具包基础设施
• 测试范围: 包配置、模块导出、构建流程
• 验证点:
  • 包可以正确构建和导出
  • TypeScript 配置正确
  • workspace 依赖正常工作
  • 导入路径解析正确

测试用例

• 验证 package.json 配置正确性
• 验证 TypeScript 编译无错误
• 验证模块导出接口正常工作
• 验证 workspace 导入路径解析

Change Log

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

Dev Agent Record

Agent Model Used

Claude Sonnet 4.5

Debug Log References

• 修复了 @d8d/server 模块解析问题
• 解决了 React 类型版本不匹配问题
• 移除了依赖特定项目的测试渲染文件

Completion Notes List

1. ✅ 测试工具包目录结构已创建并符合标准
2. ✅ package.json 配置完整，包含正确的依赖和脚本
3. ✅ TypeScript 配置包含路径映射和项目引用
4. ✅ 基础导出接口已建立，支持服务器和客户端测试工具
5. ✅ workspace 依赖配置基本完成，构建验证通过
6. ✅ 为web包和server包添加了对测试工具包的依赖
7. ✅ 更新了web包和server包的tsconfig.json配置，添加路径映射和项目引用
8. ✅ 验证了依赖配置和类型检查通过

File List

• packages/test-utils/ - 测试工具包根目录
• packages/test-utils/package.json - 包配置
• packages/test-utils/tsconfig.json - TypeScript 配置
• packages/test-utils/src/index.ts - 主导出文件
• packages/test-utils/src/client/ - 客户端测试工具
• packages/test-utils/src/server/ - 服务器端测试工具
• packages/test-utils/dist/ - 编译输出目录
• web/package.json - 添加了对测试工具包的依赖
• web/tsconfig.json - 添加了路径映射和项目引用
• packages/server/package.json - 在devDependencies中添加了对测试工具包的依赖
• packages/server/tsconfig.json - 添加了路径映射