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

Status

Draft

Story

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

Acceptance Criteria

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

Tasks / Subtasks

检查现有Vitest配置并验证其完整性 (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

Review Date: 2025-09-15

Reviewed By: Quinn (Test Architect)

Code Quality Assessment

测试框架基础设施完整，核心模块测试模板设计良好。Zod参数验证错误处理已修复，返回详细的错误信息而非通用消息。测试覆盖率达到预期标准。

Refactoring Performed

File: src/server/api/users/get.ts
- Change: 修复Zod错误处理，返回具体验证错误信息
- Why: 提供更详细的参数验证反馈，便于客户端调试
- How: 使用Zod的safeParse方法手动验证参数，返回完整的错误对象
File: src/server/api.ts
- Change: 添加全局Zod错误处理器
- Why: 确保所有API端点一致的错误处理行为
- How: 在API级别添加ZodError特定处理逻辑

Compliance Check

Coding Standards: ✓ 符合项目代码规范
Project Structure: ✓ 测试文件组织结构合理
Testing Strategy: ✓ 单元测试覆盖率达标
All ACs Met: ✓ 所有验收标准均已实现

Improvements Checklist

修复Zod参数验证错误处理 (src/server/api/users/get.ts)
添加全局API错误处理中间件 (src/server/api.ts)
验证测试覆盖率阈值配置 (vitest.config.ts)
考虑添加集成测试覆盖率报告
完善端到端测试环境配置

Security Review

密码哈希使用bcrypt正确实现，验证逻辑安全。无重大安全漏洞发现。

Performance Considerations

测试执行时间合理，mock策略适当，不会影响开发流程性能。

Files Modified During Review

src/server/api/users/get.ts
src/server/api.ts
src/server/api/users/tests/get.test.ts

Gate Status

Gate: PASS → docs/qa/gates/001.001-basic-unit-test-framework.yml Risk profile: docs/qa/assessments/001.001-risk-20250915.md NFR assessment: docs/qa/assessments/001.001-nfr-20250915.md

Recommended Status

✓ Ready for Done - 测试框架基础设施完整，核心功能测试通过，质量达标

001.001.story.md 6.4 KB História Raw