测试工具包迁移任务文档

任务概述

将 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

{
  "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引用：

// 从
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

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

添加测试脚本和依赖：

{
  "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 更新测试文件导入

调整所有测试文件中的导入语句：

// 从
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引用：

{
  "workspaces": [
    "packages/*",
    "packages/test-utils"
  ]
}

4.2 更新根 vitest.config.ts

移除已迁移的服务器集成测试配置。

4.3 更新 web/package.json

移除不再需要的测试工具依赖，添加对 @d8d/test-utils 的引用。

阶段5：验证和清理

5.1 运行测试验证

# 在 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小时

后续优化建议

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

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

test-utils-migration.md 6.1 KB 文件歷史 原始文件