# 测试工具包迁移任务文档

## 任务概述
将 `web/tests/integration/server` 目录的API集成测试迁移到 `packages/server`，并通过创建共享测试工具包实现代码复用。

## 目标
- 创建共享测试工具包 `packages/test-utils`
- 将服务器API集成测试迁移到 `packages/server/tests/integration/`
- 保持现有测试功能完整性
- 优化monorepo架构的测试组织

## 阶段1：创建共享测试工具包

### 1.1 创建 packages/test-utils 目录结构
```
packages/test-utils/
├── package.json
├── src/
│   ├── index.ts
│   ├── server/
│   │   ├── integration-test-db.ts
│   │   ├── integration-test-utils.ts
│   │   ├── test-auth.ts
│   │   └── test-db.ts
│   └── client/
│       ├── test-query.tsx
│       ├── test-render.tsx
│       └── test-router.tsx
└── tsconfig.json
```

### 1.2 配置 package.json
```json
{
  "name": "@d8d/test-utils",
  "version": "1.0.0",
  "type": "module",
  "main": "./src/index.ts",
  "types": "./src/index.ts",
  "scripts": {
    "build": "tsc",
    "dev": "tsc --watch"
  },
  "dependencies": {
    "@d8d/server": "workspace:*",
    "@hono/node-server": "^1.13.0",
    "@testing-library/react": "^14.1.2",
    "@testing-library/jest-dom": "^6.1.4",
    "@testing-library/user-event": "^14.5.1",
    "@tanstack/react-query": "^5.8.4",
    "react-router-dom": "^6.20.1",
    "bcrypt": "^5.1.1",
    "pg": "^8.11.3"
  },
  "devDependencies": {
    "@types/bcrypt": "^5.0.2",
    "@types/pg": "^8.10.9",
    "typescript": "^5.3.3"
  }
}
```

### 1.3 迁移测试工具类
从 `web/tests/utils/` 迁移以下文件：
- `integration-test-db.ts` → `packages/test-utils/src/server/integration-test-db.ts`
- `integration-test-utils.ts` → `packages/test-utils/src/server/integration-test-utils.ts`
- `test-auth.ts` → `packages/test-utils/src/server/test-auth.ts`
- `test-db.ts` → `packages/test-utils/src/server/test-db.ts`
- `test-query.tsx` → `packages/test-utils/src/client/test-query.tsx`
- `test-render.tsx` → `packages/test-utils/src/client/test-render.tsx`
- `test-router.tsx` → `packages/test-utils/src/client/test-router.tsx`

### 1.4 更新导入路径
调整所有工具类中的导入语句，使用workspace引用：
```typescript
// 从
import { IntegrationTestDatabase } from '../../utils/integration-test-db';
// 改为
import { IntegrationTestDatabase } from '@d8d/test-utils/server/integration-test-db';
```

## 阶段2：配置 packages/server 测试环境

### 2.1 创建 packages/server/vitest.config.ts
```typescript
import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    environment: 'node',
    include: ['tests/**/*.test.ts'],
    setupFiles: ['./tests/setup.ts'],
    globals: true,
  },
});
```

### 2.2 创建 packages/server/tests/setup.ts
配置测试环境，包括数据库连接和全局设置。

### 2.3 更新 packages/server/package.json
添加测试脚本和依赖：
```json
{
  "scripts": {
    "test": "vitest run",
    "test:watch": "vitest",
    "test:integration": "vitest run tests/integration/"
  },
  "devDependencies": {
    "@d8d/test-utils": "workspace:*",
    "vitest": "^1.2.2"
  }
}
```

## 阶段3：迁移集成测试文件

### 3.1 创建目标目录结构
```
packages/server/tests/
├── integration/
│   ├── auth.integration.test.ts
│   ├── backup.integration.test.ts
│   ├── files/
│   │   ├── files.integration.test.ts
│   │   └── minio.integration.test.ts
│   └── users.integration.test.ts
└── setup.ts
```

### 3.2 迁移测试文件
从 `web/tests/integration/server/` 迁移以下文件：
- `auth.integration.test.ts`
- `backup.integration.test.ts`
- `files/files.integration.test.ts`
- `files/minio.integration.test.ts`
- `users.integration.test.ts`

### 3.3 更新测试文件导入
调整所有测试文件中的导入语句：
```typescript
// 从
import { app } from '@d8d/server';
import { IntegrationTestDatabase } from '../../../utils/integration-test-db';
// 改为
import { app } from '../../src/app';
import { IntegrationTestDatabase } from '@d8d/test-utils/server/integration-test-db';
```

## 阶段4：更新根项目配置

### 4.1 更新根 package.json
添加workspace引用：
```json
{
  "workspaces": [
    "packages/*",
    "packages/test-utils"
  ]
}
```

### 4.2 更新根 vitest.config.ts
移除已迁移的服务器集成测试配置。

### 4.3 更新 web/package.json
移除不再需要的测试工具依赖，添加对 `@d8d/test-utils` 的引用。

## 阶段5：验证和清理

### 5.1 运行测试验证
```bash
# 在 packages/server 中运行集成测试
cd packages/server && pnpm test:integration

# 在 web 中运行所有测试
cd web && pnpm test
```

### 5.2 清理原目录
删除 `web/tests/integration/server/` 目录。

### 5.3 更新 CI/CD 配置
确保CI流程能够运行新的测试结构。

## 风险与缓解措施

### 风险1：数据库连接问题
- **缓解**：在迁移前备份数据库配置，确保新的测试环境使用相同的连接参数

### 风险2：导入路径错误
- **缓解**：使用TypeScript编译器检查所有导入路径，确保无错误

### 风险3：测试工具功能差异
- **缓解**：在迁移后立即运行所有测试，验证功能完整性

### 风险4：CI/CD流程中断
- **缓解**：在迁移前测试CI流程，确保新的测试命令正常工作

## 验收标准

- [ ] 所有服务器集成测试在 `packages/server` 中正常运行
- [ ] 所有web项目测试继续正常运行
- [ ] 共享测试工具包被正确引用
- [ ] CI/CD流程无错误
- [ ] 无重复代码或工具类
- [ ] 代码导入路径正确

## 时间估算

- 阶段1：2-3小时
- 阶段2：1-2小时
- 阶段3：2-3小时
- 阶段4：1小时
- 阶段5：1小时

**总计：7-10小时**

## 后续优化建议

1. 考虑将单元测试也迁移到对应的包中
2. 创建统一的测试运行脚本
3. 添加测试覆盖率报告
4. 优化测试数据管理

---

**任务创建者**: Winston 🏗️
**创建时间**: 2025-10-23
**状态**: 待执行