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

Story 001.001: 基础单元测试框架搭建

Status

Draft

Story

As a 全栈开发者 I want 建立完整的单元测试基础设施和模式 so that 我可以为现有代码库编写高质量的单元测试，确保代码质量和可维护性

Acceptance Criteria

1. 为核心模块创建单元测试模板和模式
2. 建立测试工具函数和mock数据
3. 配置测试覆盖率阈值和报告
4. 创建开发人员测试指南文档

Tasks / Subtasks

• 检查现有Jest配置并验证其完整性 (AC: 3)
• 创建核心模块的单元测试模板文件 (AC: 1)
  • UserService单元测试模板
  • AuthService单元测试模板
  • GenericCRUDService单元测试模板
• 建立测试工具函数库 (AC: 2)
  • 创建测试数据工厂函数
  • 建立常用mock工具
  • 创建测试辅助函数
• 配置测试覆盖率报告和阈值 (AC: 3)
  • 验证现有覆盖率配置
  • 设置合理的覆盖率阈值
  • 配置HTML覆盖率报告
• 创建开发人员测试指南文档 (AC: 4)
  • 编写单元测试最佳实践
  • 创建测试模式示例
  • 提供常见测试场景指南

Dev Notes

现有技术栈分析

• 测试框架: Vitest 3.2.4 [Source: package.json]
• 测试环境: Node.js环境 + happy-dom（前端测试）[Source: vitest.config.ts]
• 覆盖率工具: @vitest/coverage-v8 [Source: vitest.config.ts]
• 现有配置: Vitest配置完整，包含模块映射、覆盖率阈值、测试环境设置 [Source: vitest.config.ts]

核心模块测试需求

UserService测试重点:

• 用户CRUD操作验证
• 密码加密和验证逻辑
• 角色权限关联测试
• 错误处理和边界条件

AuthService测试重点:

• JWT令牌生成和验证
• 登录认证流程
• 会话管理测试
• 安全漏洞防护

GenericCRUDService测试重点:

• 通用CRUD操作测试
• 关联查询验证
• 分页和过滤功能
• 自定义扩展点测试

测试文件结构

基于现有项目结构 [Source: architecture.md#源码树和文件组织]:

src/
├── server/
│   ├── modules/
│   │   ├── users/
│   │   │   ├── __tests__/           # 单元测试目录
│   │   │   │   ├── user.service.test.ts
│   │   │   │   └── role.service.test.ts
│   │   ├── auth/
│   │   │   ├── __tests__/
│   │   │   │   └── auth.service.test.ts
│   ├── utils/
│   │   ├── __tests__/
│   │   │   ├── generic-crud.service.test.ts
│   │   │   └── errorHandler.test.ts

测试标准和模式

命名约定:

• 测试文件: *.test.ts 或 *.spec.ts
• 测试套件: describe('模块名称', () => {})
• 测试用例: it('应该描述预期行为', () => {})

测试结构模式:

describe('ServiceName', () => {
  describe('methodName', () => {
    it('should do something when condition', () => {
      // Arrange
      // Act
      // Assert
    });

    it('should handle error case', () => {
      // Error scenario test
    });
  });
});

技术约束和要求

• 兼容性: 必须保持现有API接口不变 [Source: epic-001-test-infrastructure.md]
• 性能: 测试执行时间应合理，不影响开发流程
• 覆盖率: 核心业务逻辑测试覆盖率 > 70% [Source: architecture.md]
• 质量: 测试代码遵循相同代码质量标准

集成点

• 构建流程: 集成到现有npm test命令
• CI/CD: 与GitHub Actions或其他CI工具集成
• 开发体验: 支持watch模式和调试

Testing

测试策略

• 单元测试范围: 单个函数、方法、类的独立测试
• Mock策略: 使用Vitest mock功能隔离外部依赖
• 数据准备: 使用工厂函数创建测试数据
• 断言库: Vitest内置断言 + 自定义匹配器

测试覆盖目标

• 行覆盖率: > 70%
• 分支覆盖率: > 70%
• 函数覆盖率: > 70%
• 语句覆盖率: > 70%

测试环境

• Node.js环境: 后端服务和工具函数测试
• jsdom环境: 前端组件测试（需要时）
• 数据库: 使用内存数据库或mock进行数据层测试

Change Log

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

Dev Agent Record

Agent Model Used

Debug Log References

Completion Notes List

File List

QA Results