file-starter/docs/stories/001.002.story.md

Story 001.002: 集成测试环境配置

Status

Ready for Review

Story

As a 后端开发者 I want 配置完整的集成测试环境和工具 so that 我可以测试API接口的完整工作流程和组件集成，确保系统各部分的正确协作

Acceptance Criteria

1. 设置API接口集成测试环境
2. 配置React组件集成测试
3. 建立数据库和外部服务mock
4. 创建集成测试最佳实践

Tasks / Subtasks

• 配置API集成测试环境 (AC: 1)
  • 设置Hono服务器测试启动
  • 配置测试数据库连接
  • 创建测试请求工具函数
• 建立React组件集成测试配置 (AC: 2)
  • 配置Testing Library集成
  • 设置组件测试渲染环境
  • 创建组件测试工具函数
• 实现数据库mock和服务stub (AC: 3)
  • 创建TypeORM测试数据源
  • 实现数据库事务回滚机制
  • 建立外部服务mock工具
• 编写集成测试最佳实践文档 (AC: 4)
  • 创建API集成测试模式
  • 编写组件集成测试指南
  • 提供mock策略和示例

Dev Notes

现有技术栈分析

• API框架: Hono 4.8.5 [Source: package.json]
• 测试库: @testing-library/react 16.3.2 [Source: package.json]
• 数据库: PostgreSQL 15 + TypeORM 0.3.25 [Source: package.json]
• 现有配置: Vitest支持happy-dom环境 [Source: vitest.config.ts]

集成测试需求

API集成测试重点:

• Hono路由端到端测试
• 认证中间件集成验证
• 数据库操作完整流程
• 错误处理链测试

React组件集成测试重点:

• 组件渲染和交互测试
• 状态管理和副作用
• 路由和导航测试
• 表单验证和提交

测试环境配置

API测试环境:

// 测试服务器启动配置
const testServer = () => {
  const app = new Hono()
  // 加载所有路由
  return app
}

// 测试数据库配置
const testDataSource = new DataSource({
  type: 'postgres',
  // 使用测试数据库或内存数据库
})

组件测试环境: 基于现有Vite + React 19配置 [Source: package.json]，需要配置：

• JS DOM环境设置
• CSS和样式处理
• React Router测试集成
• React Query测试配置

文件结构规划

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

src/
├── server/
│   ├── api/
│   │   ├── __integration_tests__/    # API集成测试
│   │   │   ├── auth.integration.test.ts
│   │   │   ├── users.integration.test.ts
│   │   │   └── roles.integration.test.ts
│   ├── __test_utils__/               # 测试工具
│   │   ├── test-server.ts
│   │   ├── test-db.ts
│   │   └── api-client.ts
├── client/
│   ├── __integration_tests__/        # 组件集成测试
│   │   ├── components/
│   │   │   ├── Form.integration.test.tsx
│   │   │   └── Table.integration.test.tsx
│   │   ├── pages/
│   │   │   ├── Login.integration.test.tsx
│   │   │   └── Dashboard.integration.test.tsx
│   ├── __test_utils__/
│   │   ├── test-render.tsx
│   │   ├── test-router.tsx
│   │   └── test-query.tsx

Mock策略和技术

数据库Mock:

• 使用测试数据库实例
• 事务回滚确保测试隔离
• 种子数据工厂函数

外部服务Mock:

• Vitest mock模块功能
• Mock Service Worker (MSW) for HTTP
• 自定义stub实现

认证Mock:

• Mock JWT令牌生成
• 模拟用户会话
• 权限验证stub

集成测试模式

API测试模式:

describe('API Integration', () => {
  let server: Hono

  beforeAll(async () => {
    server = createTestServer()
    await setupTestDatabase()
  })

  it('should return users list', async () => {
    const response = await server.request('/api/v1/users')
    expect(response.status).toBe(200)
  })
})

组件测试模式:

describe('Component Integration', () => {
  it('should render and interact', async () => {
    render(<LoginForm />)

    await userEvent.type(screen.getByLabelText('Email'), 'test@example.com')
    await userEvent.click(screen.getByRole('button', { name: 'Login' }))

    expect(...).toBeInTheDocument()
  })
})

技术约束和要求

• 性能: 集成测试执行时间控制在合理范围内
• 隔离性: 测试之间完全隔离，无状态污染
• 可靠性: 测试结果稳定可靠，无随机失败
• 可维护性: 测试代码清晰易维护

集成点

• 构建流程: 集成到现有测试命令
• CI/CD: 支持并行测试执行
• 开发体验: 快速反馈和调试支持

Testing

测试策略

• 集成测试范围: 多组件/服务协作测试
• 环境要求: 接近生产环境的测试配置
• 数据管理: 测试数据生命周期管理
• 网络模拟: HTTP请求拦截和mock

测试覆盖目标

• API端点: 主要业务端点100%覆盖
• 关键流程: 用户旅程和核心业务流程
• 错误场景: 主要错误处理路径
• 性能基准: 关键接口性能验证

测试环境

• Node.js服务器: Hono应用完整启动
• 数据库: 测试数据库实例
• 浏览器环境: jsdom模拟浏览器
• 网络环境: 模拟HTTP请求响应

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