lanyuanxiaoyao
9359ca7f62
- 采用 Ant Design 5 作为 UI 组件库，替换自定义组件 - 集成 React Router v7 提供路由导航 - 使用 TanStack Query v5 管理数据获取和缓存 - 建立 Vitest + React Testing Library 测试体系 - 添加 Playwright E2E 测试覆盖 - 使用 MSW mock API 响应 - 配置 TypeScript strict 模式 - 采用 SCSS Modules 组织样式 - 更新 OpenSpec 规格以反映前端架构变更 - 归档 frontend-refactor 变更记录
189 lines
6.6 KiB
Markdown
189 lines
6.6 KiB
Markdown
# 前端测试体系
|
||
|
||
## Purpose
|
||
|
||
建立前端测试体系，覆盖单元测试、组件测试和 E2E 测试，确保前端代码质量和功能正确性。
|
||
|
||
## Requirements
|
||
|
||
### Requirement: 建立前端单元测试体系
|
||
|
||
前端 SHALL 使用 Vitest 建立单元测试体系，覆盖 API 层和自定义 Hooks。
|
||
|
||
#### Scenario: API 客户端单测
|
||
|
||
- **WHEN** 运行 api/client.ts 的单元测试
|
||
- **THEN** SHALL 覆盖 request<T>() 的正常响应解析
|
||
- **THEN** SHALL 覆盖 HTTP 错误状态码（4xx、5xx）的 ApiError 抛出
|
||
- **THEN** SHALL 覆盖网络错误的错误处理
|
||
- **THEN** SHALL 覆盖 snake_case → camelCase 响应字段转换
|
||
- **THEN** SHALL 覆盖 camelCase → snake_case 请求字段转换
|
||
|
||
#### Scenario: API 模块单测
|
||
|
||
- **WHEN** 运行 api/providers.ts、api/models.ts、api/stats.ts 的单元测试
|
||
- **THEN** SHALL 覆盖所有 CRUD 函数的正确调用
|
||
- **THEN** SHALL 覆盖参数传递和返回值类型
|
||
|
||
#### Scenario: 自定义 Hooks 单测
|
||
|
||
- **WHEN** 运行 hooks/ 目录下的单元测试
|
||
- **THEN** SHALL 使用 @tanstack/react-query 的 renderHook 测试工具
|
||
- **THEN** SHALL 覆盖 useQuery 数据获取（成功和失败）
|
||
- **THEN** SHALL 覆盖 useMutation 写操作后的缓存失效
|
||
- **THEN** SHALL 使用独立的测试 QueryClient（关闭 retry 和缓存）
|
||
|
||
### Requirement: 建立前端组件测试体系
|
||
|
||
前端 SHALL 使用 React Testing Library 建立组件测试体系。
|
||
|
||
#### Scenario: ProviderTable 组件测试
|
||
|
||
- **WHEN** 运行 ProviderTable 组件测试
|
||
- **THEN** SHALL 验证供应商列表正确渲染
|
||
- **THEN** SHALL 验证点击"添加"按钮弹出 Modal
|
||
- **THEN** SHALL 验证点击"编辑"按钮弹出预填充的 Modal
|
||
- **THEN** SHALL 验证删除操作触发 Popconfirm 确认
|
||
|
||
#### Scenario: ProviderForm 组件测试
|
||
|
||
- **WHEN** 运行 ProviderForm 组件测试
|
||
- **THEN** SHALL 验证表单校验规则（必填字段、URL 格式）
|
||
- **THEN** SHALL 验证提交成功后调用 onSave 回调
|
||
- **THEN** SHALL 验证编辑模式下字段预填充
|
||
|
||
#### Scenario: StatsTable 组件测试
|
||
|
||
- **WHEN** 运行 StatsTable 组件测试
|
||
- **THEN** SHALL 验证筛选条件交互（供应商选择、日期范围）
|
||
- **THEN** SHALL 验证统计数据正确展示
|
||
|
||
### Requirement: 建立 E2E 测试体系
|
||
|
||
前端 SHALL 使用 Playwright 建立端到端测试体系。
|
||
|
||
#### Scenario: 供应商管理 E2E 测试
|
||
|
||
- **WHEN** 运行供应商管理的 E2E 测试
|
||
- **THEN** SHALL 测试完整的供应商创建流程
|
||
- **THEN** SHALL 测试供应商编辑流程
|
||
- **THEN** SHALL 测试供应商删除流程（含确认弹窗）
|
||
- **THEN** SHALL 测试供应商展开后的模型管理
|
||
|
||
#### Scenario: 统计查询 E2E 测试
|
||
|
||
- **WHEN** 运行统计查询的 E2E 测试
|
||
- **THEN** SHALL 测试页面加载和默认数据展示
|
||
- **THEN** SHALL 测试按供应商筛选
|
||
- **THEN** SHALL 测试按日期范围筛选
|
||
|
||
### Requirement: 使用 MSW 进行 API Mock
|
||
|
||
前端测试 SHALL 使用 MSW (Mock Service Worker) 模拟后端 API 响应。
|
||
|
||
#### Scenario: 测试环境 MSW 配置
|
||
|
||
- **WHEN** 初始化测试环境
|
||
- **THEN** SHALL 配置 MSW server 处理所有 /api/* 请求
|
||
- **THEN** SHALL 在 setup.ts 中全局启动和清理 MSW server
|
||
|
||
#### Scenario: Mock 响应定义
|
||
|
||
- **WHEN** 编写需要 API 交互的测试
|
||
- **THEN** SHALL 使用 MSW handler 定义期望的 API 响应
|
||
- **THEN** SHALL 支持成功和失败两种响应场景
|
||
- **THEN** SHALL 在每个测试用例后重置 handler
|
||
|
||
### Requirement: 测试文件组织
|
||
|
||
前端测试文件 SHALL 按层级组织在 src/__tests__/ 目录下。
|
||
|
||
#### Scenario: 目录结构
|
||
|
||
- **WHEN** 组织测试文件
|
||
- **THEN** src/__tests__/setup.ts SHALL 包含全局测试配置
|
||
- **THEN** src/__tests__/api/ SHALL 包含 API 层单测
|
||
- **THEN** src/__tests__/hooks/ SHALL 包含 Hooks 单测
|
||
- **THEN** src/__tests__/components/ SHALL 包含组件测试
|
||
- **THEN** e2e/ 目录（项目根目录下）SHALL 包含 Playwright E2E 测试
|
||
|
||
### Requirement: Vitest 配置
|
||
|
||
前端 SHALL 配置 Vitest 作为测试运行器。
|
||
|
||
#### Scenario: 测试环境配置
|
||
|
||
- **WHEN** 运行 vitest
|
||
- **THEN** SHALL 使用 jsdom 作为测试环境
|
||
- **THEN** SHALL 配置 setupFiles 指向 src/__tests__/setup.ts
|
||
- **THEN** SHALL 配置路径别名 @/ 与 tsconfig 一致
|
||
- **THEN** SHALL 配置 @testing-library/jest-dom 匹配器
|
||
|
||
#### Scenario: 覆盖率配置
|
||
|
||
- **WHEN** 运行覆盖率报告
|
||
- **THEN** SHALL 使用 @vitest/coverage-v8 提供者
|
||
- **THEN** SHALL 覆盖 src/ 下的所有源文件
|
||
|
||
### Requirement: 建立前端单元测试覆盖
|
||
|
||
前端代码 SHALL 建立单元测试覆盖，纳入整体测试覆盖率统计。
|
||
|
||
#### Scenario: API 层测试覆盖
|
||
|
||
- **WHEN** 运行前端 API 层的单元测试
|
||
- **THEN** SHALL 覆盖 api/client.ts 的请求封装和字段转换逻辑
|
||
- **THEN** SHALL 覆盖 api/providers.ts、api/models.ts、api/stats.ts 的所有函数
|
||
- **THEN** SHALL 使用 MSW mock API 响应
|
||
|
||
#### Scenario: Hooks 测试覆盖
|
||
|
||
- **WHEN** 运行前端 Hooks 的单元测试
|
||
- **THEN** SHALL 覆盖 useProviders、useModels、useStats 的查询和变更逻辑
|
||
- **THEN** SHALL 验证缓存失效和自动刷新行为
|
||
|
||
### Requirement: 建立前端组件测试覆盖
|
||
|
||
前端 SHALL 使用 React Testing Library 建立组件测试覆盖。
|
||
|
||
#### Scenario: 页面组件测试覆盖
|
||
|
||
- **WHEN** 运行前端组件测试
|
||
- **THEN** SHALL 覆盖 ProviderTable 的列表渲染和交互操作
|
||
- **THEN** SHALL 覆盖 ProviderForm 的表单校验和提交
|
||
- **THEN** SHALL 覆盖 ModelForm 的表单校验和提交
|
||
- **THEN** SHALL 覆盖 StatsTable 的筛选和数据展示
|
||
|
||
### Requirement: 建立前端 E2E 测试覆盖
|
||
|
||
前端 SHALL 使用 Playwright 建立 E2E 测试覆盖。
|
||
|
||
#### Scenario: 供应商管理 E2E 覆盖
|
||
|
||
- **WHEN** 运行 E2E 测试
|
||
- **THEN** SHALL 覆盖供应商创建、编辑、删除的完整用户流程
|
||
- **THEN** SHALL 覆盖模型创建、编辑、删除的完整用户流程
|
||
|
||
#### Scenario: 统计查询 E2E 覆盖
|
||
|
||
- **WHEN** 运行 E2E 测试
|
||
- **THEN** SHALL 覆盖统计页面的加载和筛选查询流程
|
||
- **THEN** SHALL 覆盖页面间的导航切换
|
||
|
||
### Requirement: 前端测试集成到构建流程
|
||
|
||
前端测试 SHALL 集成到项目的构建和验证流程中。
|
||
|
||
#### Scenario: 运行前端测试命令
|
||
|
||
- **WHEN** 在 frontend/ 目录执行测试命令
|
||
- **THEN** SHALL 运行所有 Vitest 单元测试和组件测试
|
||
- **THEN** SHALL 显示测试结果
|
||
- **THEN** SHALL 在测试失败时返回非零退出码
|
||
|
||
#### Scenario: 运行前端 E2E 测试命令
|
||
|
||
- **WHEN** 在 frontend/ 目录执行 E2E 测试命令
|
||
- **THEN** SHALL 启动 Playwright 运行 E2E 测试
|
||
- **THEN** SHALL 在测试失败时返回非零退出码
|