lanyuanxiaoyao
8793fbd786
- 新增 jsdom + @testing-library/react 组件测试环境 - 新增 12 个组件测试，覆盖所有前端组件 - 补充后端 middleware 和 helpers 单元测试 - 删除伪测试 use-target-detail-logic.test.ts - 精简过度枚举的 color-threshold.test.ts - 新增 bunfig.toml 配置测试 preload - 更新 DEVELOPMENT.md 测试章节 - 安装 @types/jsdom 修复类型声明
73 lines
3.8 KiB
Markdown
73 lines
3.8 KiB
Markdown
## Purpose
|
||
|
||
定义前端组件测试基础设施和覆盖要求，确保所有 React 组件的渲染、交互和状态流转行为经过验证。
|
||
|
||
## Requirements
|
||
|
||
### Requirement: jsdom 测试环境配置
|
||
项目 SHALL 通过 `tests/setup.ts` preload 脚本为组件测试提供 jsdom DOM 环境，包含 TDesign 组件所需的浏览器 API polyfill。
|
||
|
||
#### Scenario: 组件测试可以渲染 React 组件
|
||
- **WHEN** 组件测试文件使用 `@testing-library/react` 的 `render` 函数渲染组件
|
||
- **THEN** 组件 SHALL 在 jsdom 环境中正常渲染，可通过 `screen` 查询 DOM 元素
|
||
|
||
#### Scenario: TDesign 组件依赖的浏览器 API 可用
|
||
- **WHEN** 组件测试渲染使用了 TDesign 组件（Table、Drawer、Skeleton 等）的业务组件
|
||
- **THEN** jsdom 环境 SHALL 提供 `ResizeObserver`、`IntersectionObserver`、`window.matchMedia` 等 polyfill，不因缺失 API 而抛错
|
||
|
||
#### Scenario: recharts 图表组件被 mock
|
||
- **WHEN** 组件测试渲染包含 recharts 图表的组件
|
||
- **THEN** recharts 模块 SHALL 被 mock 为简单占位元素，不依赖 SVG 渲染能力
|
||
|
||
### Requirement: 组件测试使用 @testing-library/react
|
||
项目 SHALL 使用 `@testing-library/react` 作为组件测试工具，遵循"测试用户行为而非实现细节"的原则。
|
||
|
||
#### Scenario: 通过用户可见内容查询元素
|
||
- **WHEN** 测试需要查找页面元素
|
||
- **THEN** 测试 SHALL 优先使用 `getByText`、`getByRole`、`getByLabelText` 等语义化查询，而非 CSS 选择器或 testId
|
||
|
||
#### Scenario: 通过用户交互触发行为
|
||
- **WHEN** 测试需要模拟用户操作
|
||
- **THEN** 测试 SHALL 使用 `fireEvent` 或 `userEvent` 模拟点击、输入等操作，而非直接调用组件内部方法
|
||
|
||
### Requirement: 所有前端组件 SHALL 有组件测试覆盖
|
||
项目 SHALL 为 `src/web/components/` 下的每个组件和 `src/web/app.tsx` 提供对应的组件测试文件。
|
||
|
||
#### Scenario: 纯展示组件测试
|
||
- **WHEN** 组件为纯展示组件（如 StatusDot、SummaryCards）
|
||
- **THEN** 测试 SHALL 验证给定 props 时渲染正确的文本和结构，以及 null/空数据时的条件渲染
|
||
|
||
#### Scenario: 交互组件测试
|
||
- **WHEN** 组件包含用户交互（如 TargetDetailDrawer 的 Tab 切换、RefreshCountdown 的按钮点击）
|
||
- **THEN** 测试 SHALL 验证交互触发正确的回调函数调用和参数传递
|
||
|
||
#### Scenario: 条件渲染测试
|
||
- **WHEN** 组件根据 loading/error/empty 状态展示不同内容（如 OverviewTab）
|
||
- **THEN** 测试 SHALL 覆盖所有条件分支：loading skeleton、正常数据渲染、空数据占位
|
||
|
||
#### Scenario: 数据驱动组件测试
|
||
- **WHEN** 组件接收列表数据渲染（如 TargetBoard 的分组、HistoryTab 的表格）
|
||
- **THEN** 测试 SHALL 验证数据正确映射到 UI 元素，包括空列表和多项数据的情况
|
||
|
||
### Requirement: 组件测试的 Mock 边界
|
||
组件测试 SHALL 只 mock 系统边界（网络请求），不 mock 内部实现。
|
||
|
||
#### Scenario: Mock fetch 而非 React Query
|
||
- **WHEN** 组件通过 `@tanstack/react-query` 发起数据请求
|
||
- **THEN** 测试 SHALL mock `globalThis.fetch` 返回预设响应，使用真实的 `QueryClientProvider` 包裹组件
|
||
|
||
#### Scenario: 不 mock TDesign 组件
|
||
- **WHEN** 业务组件使用 TDesign 组件
|
||
- **THEN** 测试 SHALL 真实渲染 TDesign 组件，验证 props 传递和集成行为的正确性
|
||
|
||
### Requirement: 组件测试文件组织
|
||
组件测试文件 SHALL 位于 `tests/web/components/` 目录下，文件名与组件名对应。
|
||
|
||
#### Scenario: 测试文件命名
|
||
- **WHEN** 为 `src/web/components/TargetBoard.tsx` 编写组件测试
|
||
- **THEN** 测试文件 SHALL 位于 `tests/web/components/TargetBoard.test.tsx`
|
||
|
||
#### Scenario: App 组件测试位置
|
||
- **WHEN** 为 `src/web/app.tsx` 编写组件测试
|
||
- **THEN** 测试文件 SHALL 位于 `tests/web/components/App.test.tsx`
|