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

**父史诗**: 史诗005 - Server测试迁移优化
[docs/prd/epic-005-server-test-migration.md](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
- [x] 在packages/server/package.json中添加测试脚本 (AC: 1)
  - [x] 添加test脚本运行所有测试
  - [x] 添加test:unit脚本运行单元测试
  - [x] 添加test:integration脚本运行集成测试
  - [x] 添加test:coverage脚本生成覆盖率报告
  - [x] 添加test:typecheck脚本进行类型检查
- [x] 创建packages/server/vitest.config.ts配置文件 (AC: 2)
  - [x] 配置Node.js测试环境
  - [x] 设置测试别名映射
  - [x] 配置覆盖率报告
  - [x] 设置测试超时和排除规则
- [x] 建立packages/server/tests目录结构 (AC: 3)
  - [x] 创建tests/unit目录用于单元测试
  - [x] 创建tests/integration目录用于集成测试
  - [x] 创建tests/utils目录用于测试工具
  - [x] 创建tests/fixtures目录用于测试数据
- [x] 配置测试依赖和工具 (AC: 4)
  - [x] 添加vitest和测试相关依赖到devDependencies
  - [x] 配置测试数据库连接
  - [x] 创建测试设置文件
  - [x] 复制web/tests/utils/server目录下的测试工具
  - [x] 验证测试环境正常工作

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

## QA Results