---
title: 测试文档
order: 1
category: pro
---

# PisellScrollView 测试用例文档

## 1. 测试概述

### 1.1 测试目标

- 验证 PisellScrollView 组件的所有功能正常运行
- 确保组件在各种场景下的表现符合预期
- 保证组件的稳定性和可靠性
- 验证滚动事件、滚动按钮、Ref 方法等功能

### 1.2 测试范围

- 基础功能测试
- 滚动方向控制测试
- 滚动条样式测试
- 滚动事件监听测试
- 滚动按钮功能测试
- Ref 方法测试
- 吸附滚动测试
- 边界条件测试
- 设计模式测试

### 1.3 测试环境

- React 版本：18.x
- TypeScript 版本：5.x
- Ant Design 版本：5.x
- 测试框架：Vitest + React Testing Library
- 测试工具：@testing-library/react, @testing-library/user-event, @testing-library/jest-dom

## 2. 功能测试用例

### 2.1 基础渲染测试

#### 测试用例 2.1.1：默认渲染

**测试目的：** 验证组件能够正常渲染  
**测试步骤：**

1. 渲染 PisellScrollView 组件，不传入任何 props
2. 检查组件是否成功挂载

**期望结果：**

- 组件成功渲染
- 显示滚动视图容器

**测试类型：** 自动化测试

---

#### 测试用例 2.1.2：渲染子元素

**测试目的：** 验证子元素能够正确渲染  
**测试步骤：**

1. 传入子元素
2. 检查子元素是否显示

**期望结果：**

- 子元素成功渲染
- 子元素内容正确显示

**测试类型：** 自动化测试

---

#### 测试用例 2.1.3：自定义类名和样式

**测试目的：** 验证自定义类名和样式能够正确应用  
**测试步骤：**

1. 传入 className 和 style props
2. 检查元素是否应用了自定义类名和样式

**期望结果：**

- 容器元素包含自定义类名
- 容器元素应用了自定义样式

**测试类型：** 自动化测试

---

### 2.2 滚动方向测试

#### 测试用例 2.2.1：auto 模式

**测试目的：** 验证 auto 滚动模式  
**测试步骤：**

1. 设置 `overflow="auto"`
2. 检查滚动行为

**期望结果：**

- 根据内容自动显示滚动条
- 可以正常滚动

**测试类型：** 自动化测试

---

#### 测试用例 2.2.2：x 方向滚动

**测试目的：** 验证水平滚动功能  
**测试步骤：**

1. 设置 `overflow="x"`
2. 添加宽度超出容器的内容
3. 检查是否可以水平滚动

**期望结果：**

- 只显示水平滚动条
- 可以水平滚动
- 不能垂直滚动

**测试类型：** 自动化测试

---

#### 测试用例 2.2.3：y 方向滚动

**测试目的：** 验证垂直滚动功能  
**测试步骤：**

1. 设置 `overflow="y"`
2. 添加高度超出容器的内容
3. 检查是否可以垂直滚动

**期望结果：**

- 只显示垂直滚动条
- 可以垂直滚动
- 不能水平滚动

**测试类型：** 自动化测试

---

#### 测试用例 2.2.4：both 双向滚动

**测试目的：** 验证双向滚动功能  
**测试步骤：**

1. 设置 `overflow="both"`
2. 添加宽度和高度都超出容器的内容
3. 检查是否可以双向滚动

**期望结果：**

- 同时显示水平和垂直滚动条
- 可以双向滚动

**测试类型：** 自动化测试

---

#### 测试用例 2.2.5：hidden 隐藏滚动

**测试目的：** 验证隐藏滚动功能  
**测试步骤：**

1. 设置 `overflow="hidden"`
2. 检查滚动条是否隐藏

**期望结果：**

- 滚动条隐藏
- 内容不可滚动

**测试类型：** 自动化测试

---

### 2.3 滚动条样式测试

#### 测试用例 2.3.1：default 样式

**测试目的：** 验证默认滚动条样式  
**测试步骤：**

1. 设置 `scrollbarStyle="default"`
2. 检查滚动条样式

**期望结果：**

- 显示默认样式的滚动条
- 滚动条正常显示

**测试类型：** 自动化测试

---

#### 测试用例 2.3.2：thin 样式

**测试目的：** 验证细滚动条样式  
**测试步骤：**

1. 设置 `scrollbarStyle="thin"`
2. 检查滚动条样式

**期望结果：**

- 显示细滚动条
- 应用 thin 样式类

**测试类型：** 自动化测试

---

#### 测试用例 2.3.3：minimal 样式

**测试目的：** 验证最小化滚动条样式  
**测试步骤：**

1. 设置 `scrollbarStyle="minimal"`
2. 检查滚动条样式

**期望结果：**

- 显示最小化滚动条
- 应用 minimal 样式类

**测试类型：** 自动化测试

---

#### 测试用例 2.3.4：none 隐藏滚动条

**测试目的：** 验证隐藏滚动条功能  
**测试步骤：**

1. 设置 `scrollbarStyle="none"`
2. 检查滚动条是否隐藏

**期望结果：**

- 滚动条隐藏
- 应用 hide-scrollbar 类
- 内容仍可滚动

**测试类型：** 自动化测试

---

#### 测试用例 2.3.5：custom 自定义样式

**测试目的：** 验证自定义滚动条样式  
**测试步骤：**

1. 设置 `scrollbarStyle="custom"` 和 `scrollbarClassName="my-scrollbar"`
2. 检查是否应用自定义类名

**期望结果：**

- 应用自定义类名
- 可以通过 CSS 自定义样式

**测试类型：** 自动化测试

---

### 2.4 尺寸测试

#### 测试用例 2.4.1：width 和 height

**测试目的：** 验证宽度和高度设置  
**测试步骤：**

1. 设置 `width="600px"` 和 `height="400px"`
2. 检查容器尺寸

**期望结果：**

- 容器宽度为 600px
- 容器高度为 400px

**测试类型：** 自动化测试

---

#### 测试用例 2.4.2：maxWidth 和 maxHeight

**测试目的：** 验证最大宽度和高度设置  
**测试步骤：**

1. 设置 `maxWidth="800px"` 和 `maxHeight="600px"`
2. 检查容器最大尺寸

**期望结果：**

- 容器最大宽度为 800px
- 容器最大高度为 600px

**测试类型：** 自动化测试

---

#### 测试用例 2.4.3：minWidth 和 minHeight

**测试目的：** 验证最小宽度和高度设置  
**测试步骤：**

1. 设置 `minWidth="200px"` 和 `minHeight="100px"`
2. 检查容器最小尺寸

**期望结果：**

- 容器最小宽度为 200px
- 容器最小高度为 100px

**测试类型：** 自动化测试

---

### 2.5 滚动事件测试

#### 测试用例 2.5.1：onScroll 事件

**测试目的：** 验证滚动事件触发  
**测试步骤：**

1. 设置 `onScroll` 回调
2. 触发滚动操作
3. 检查回调是否被调用

**期望结果：**

- onScroll 回调被调用
- 回调参数包含正确的滚动数据

**测试类型：** 自动化测试

---

#### 测试用例 2.5.2：onScrollStart 事件

**测试目的：** 验证开始滚动事件触发  
**测试步骤：**

1. 设置 `onScrollStart` 回调
2. 开始滚动操作
3. 检查回调是否被调用

**期望结果：**

- onScrollStart 回调被调用
- 在滚动开始时触发

**测试类型：** 自动化测试

---

#### 测试用例 2.5.3：onScrollEnd 事件

**测试目的：** 验证滚动结束事件触发  
**测试步骤：**

1. 设置 `onScrollEnd` 回调和 `scrollEndDelay`
2. 滚动并停止
3. 等待延迟时间后检查回调是否被调用

**期望结果：**

- onScrollEnd 回调被调用
- 在滚动结束后延迟触发

**测试类型：** 自动化测试

---

#### 测试用例 2.5.4：onReachTop 事件

**测试目的：** 验证到达顶部事件触发  
**测试步骤：**

1. 设置 `onReachTop` 回调和 `reachThreshold`
2. 滚动到顶部
3. 检查回调是否被调用

**期望结果：**

- onReachTop 回调被调用
- 在到达顶部时触发

**测试类型：** 自动化测试

---

#### 测试用例 2.5.5：onReachBottom 事件

**测试目的：** 验证到达底部事件触发  
**测试步骤：**

1. 设置 `onReachBottom` 回调和 `reachThreshold`
2. 滚动到底部
3. 检查回调是否被调用

**期望结果：**

- onReachBottom 回调被调用
- 在到达底部时触发

**测试类型：** 自动化测试

---

#### 测试用例 2.5.6：onReachLeft 和 onReachRight 事件

**测试目的：** 验证到达左右边界事件触发  
**测试步骤：**

1. 设置 `onReachLeft` 和 `onReachRight` 回调
2. 水平滚动到左右边界
3. 检查回调是否被调用

**期望结果：**

- onReachLeft 在到达左边界时触发
- onReachRight 在到达右边界时触发

**测试类型：** 自动化测试

---

### 2.6 滚动按钮测试

#### 测试用例 2.6.1：右侧箭头按钮

**测试目的：** 验证右侧箭头按钮显示和功能  
**测试步骤：**

1. 设置 `scrollActionsConfig={{ show: true, type: 'rArrows' }}`
2. 检查按钮是否显示
3. 点击按钮检查是否滚动

**期望结果：**

- 右侧箭头按钮显示
- 点击按钮可以向右滚动

**测试类型：** 自动化测试

---

#### 测试用例 2.6.2：左右箭头按钮

**测试目的：** 验证左右箭头按钮显示和功能  
**测试步骤：**

1. 设置 `scrollActionsConfig={{ show: true, type: 'lrArrows' }}`
2. 检查按钮是否显示
3. 点击左右按钮检查是否滚动

**期望结果：**

- 左右箭头按钮都显示
- 点击左按钮向左滚动
- 点击右按钮向右滚动

**测试类型：** 自动化测试

---

#### 测试用例 2.6.3：上下箭头按钮

**测试目的：** 验证上下箭头按钮显示和功能  
**测试步骤：**

1. 设置 `scrollActionsConfig={{ show: true, type: 'tbArrows' }}`
2. 检查按钮是否显示
3. 点击上下按钮检查是否滚动

**期望结果：**

- 上下箭头按钮都显示
- 点击上按钮向上滚动
- 点击下按钮向下滚动

**测试类型：** 自动化测试

---

#### 测试用例 2.6.4：返回顶部按钮

**测试目的：** 验证返回顶部按钮显示和功能  
**测试步骤：**

1. 设置 `scrollActionsConfig={{ show: true, type: 'backTop' }}`
2. 滚动到底部
3. 检查按钮是否显示
4. 点击按钮检查是否滚动到顶部

**期望结果：**

- 返回顶部按钮显示
- 点击按钮滚动到顶部

**测试类型：** 自动化测试

---

#### 测试用例 2.6.5：隐藏滚动按钮

**测试目的：** 验证隐藏滚动按钮功能  
**测试步骤：**

1. 设置 `scrollActionsConfig={{ show: false }}`
2. 检查按钮是否隐藏

**期望结果：**

- 滚动按钮不显示

**测试类型：** 自动化测试

---

#### 测试用例 2.6.6：自定义滚动距离

**测试目的：** 验证自定义滚动距离功能  
**测试步骤：**

1. 设置 `scrollActionsConfig={{ scrollDistance: 500 }}`
2. 点击滚动按钮
3. 检查滚动距离

**期望结果：**

- 每次滚动 500px

**测试类型：** 自动化测试

---

### 2.7 Ref 方法测试

#### 测试用例 2.7.1：scrollToTop

**测试目的：** 验证 scrollToTop 方法  
**测试步骤：**

1. 获取组件 ref
2. 调用 `scrollToTop()` 方法
3. 检查是否滚动到顶部

**期望结果：**

- 滚动到顶部
- scrollTop 为 0

**测试类型：** 自动化测试

---

#### 测试用例 2.7.2：scrollToBottom

**测试目的：** 验证 scrollToBottom 方法  
**测试步骤：**

1. 获取组件 ref
2. 调用 `scrollToBottom()` 方法
3. 检查是否滚动到底部

**期望结果：**

- 滚动到底部
- scrollTop 为最大值

**测试类型：** 自动化测试

---

#### 测试用例 2.7.3：scrollToLeft 和 scrollToRight

**测试目的：** 验证 scrollToLeft 和 scrollToRight 方法  
**测试步骤：**

1. 获取组件 ref
2. 调用 `scrollToLeft()` 和 `scrollToRight()` 方法
3. 检查是否滚动到左右边界

**期望结果：**

- scrollToLeft 滚动到最左侧
- scrollToRight 滚动到最右侧

**测试类型：** 自动化测试

---

#### 测试用例 2.7.4：scrollTo

**测试目的：** 验证 scrollTo 方法  
**测试步骤：**

1. 获取组件 ref
2. 调用 `scrollTo({ scrollTop: 200, scrollLeft: 100 })`
3. 检查滚动位置

**期望结果：**

- scrollTop 为 200
- scrollLeft 为 100

**测试类型：** 自动化测试

---

#### 测试用例 2.7.5：scrollToElement

**测试目的：** 验证 scrollToElement 方法  
**测试步骤：**

1. 获取组件 ref
2. 在内容中添加带 id 的元素
3. 调用 `scrollToElement({ targetId: 'element-id' })`
4. 检查是否滚动到目标元素

**期望结果：**

- 滚动到目标元素位置
- 元素在视口中可见

**测试类型：** 自动化测试

---

#### 测试用例 2.7.6：scrollToPercentage

**测试目的：** 验证 scrollToPercentage 方法  
**测试步骤：**

1. 获取组件 ref
2. 调用 `scrollToPercentage({ percentY: 50 })`
3. 检查滚动位置

**期望结果：**

- 滚动到 50% 位置
- percentY 为 50

**测试类型：** 自动化测试

---

#### 测试用例 2.7.7：getScrollData

**测试目的：** 验证 getScrollData 方法  
**测试步骤：**

1. 获取组件 ref
2. 调用 `getScrollData()` 方法
3. 检查返回的数据结构

**期望结果：**

- 返回滚动数据对象
- 包含 scrollTop、scrollLeft、percentY、percentX 等属性

**测试类型：** 自动化测试

---

#### 测试用例 2.7.8：getScrollContainer

**测试目的：** 验证 getScrollContainer 方法  
**测试步骤：**

1. 获取组件 ref
2. 调用 `getScrollContainer()` 方法
3. 检查返回的 DOM 元素

**期望结果：**

- 返回滚动容器 DOM 元素
- 元素类型为 HTMLElement

**测试类型：** 自动化测试

---

### 2.8 吸附滚动测试

#### 测试用例 2.8.1：启用吸附滚动

**测试目的：** 验证吸附滚动功能  
**测试步骤：**

1. 设置 `snapScroll={{ enabled: true, type: 'mandatory' }}`
2. 添加多个可吸附的元素
3. 滚动并检查是否吸附

**期望结果：**

- 滚动时自动吸附到元素位置
- 应用 scroll-snap-type 样式

**测试类型：** 自动化测试

---

#### 测试用例 2.8.2：proximity 类型

**测试目的：** 验证 proximity 吸附类型  
**测试步骤：**

1. 设置 `snapScroll={{ enabled: true, type: 'proximity' }}`
2. 滚动并检查吸附行为

**期望结果：**

- 应用 proximity 吸附类型
- 吸附行为更柔和

**测试类型：** 自动化测试

---

#### 测试用例 2.8.3：吸附回调

**测试目的：** 验证吸附回调函数  
**测试步骤：**

1. 设置 `snapScroll={{ onSnapStart, onSnapEnd }}`
2. 触发吸附滚动
3. 检查回调是否被调用

**期望结果：**

- onSnapStart 在吸附开始时调用
- onSnapEnd 在吸附结束时调用

**测试类型：** 自动化测试

---

### 2.9 视图监听测试

#### 测试用例 2.9.1：IntersectionObserver 配置

**测试目的：** 验证 IntersectionObserver 功能  
**测试步骤：**

1. 设置 `intersection={{ enabled: true, targetSelector: '.observe-item' }}`
2. 添加可观察的元素
3. 滚动并检查回调是否触发

**期望结果：**

- 元素进入视图时触发 onEnterViewport
- 元素离开视图时触发 onLeaveViewport

**测试类型：** 自动化测试

---

### 2.10 边界条件测试

#### 测试用例 2.10.1：空子元素

**测试目的：** 验证空子元素时的行为  
**测试步骤：**

1. 渲染组件，不传入子元素
2. 检查组件是否正常渲染

**期望结果：**

- 组件正常渲染
- 不报错

**测试类型：** 自动化测试

---

#### 测试用例 2.10.2：内容不足滚动

**测试目的：** 验证内容不足时的行为  
**测试步骤：**

1. 添加高度小于容器的内容
2. 检查滚动条是否隐藏

**期望结果：**

- 滚动条隐藏
- 不显示滚动按钮

**测试类型：** 自动化测试

---

#### 测试用例 2.10.3：scrollToElement 目标不存在

**测试目的：** 验证目标元素不存在时的行为  
**测试步骤：**

1. 调用 `scrollToElement({ targetId: 'non-existent' })`
2. 检查是否报错

**期望结果：**

- 不报错
- 静默失败

**测试类型：** 自动化测试

---

### 2.11 设计模式测试

#### 测试用例 2.11.1：设计模式 ref

**测试目的：** 验证设计模式下 ref 的行为  
**测试步骤：**

1. 设置 `__designMode={true}`
2. 获取 ref
3. 检查 ref.current 的类型

**期望结果：**

- ref.current 为 DOM 元素
- 不是方法对象

**测试类型：** 自动化测试

---

## 3. 集成测试

### 3.1 综合功能测试

#### 测试用例 3.1.1：完整功能组合

**测试目的：** 验证多个功能组合使用  
**测试步骤：**

1. 同时启用滚动按钮、吸附滚动、事件监听
2. 执行各种操作
3. 检查所有功能是否正常

**期望结果：**

- 所有功能正常工作
- 没有冲突

**测试类型：** 自动化测试

---

## 4. 性能测试

### 4.1 滚动性能测试

#### 测试用例 4.1.1：大量内容滚动

**测试目的：** 验证大量内容时的滚动性能  
**测试步骤：**

1. 添加大量内容（1000+ 项）
2. 执行滚动操作
3. 检查性能

**期望结果：**

- 滚动流畅
- 无明显卡顿

**测试类型：** 人工测试

---

## 5. 兼容性测试

### 5.1 浏览器兼容性

#### 测试用例 5.1.1：Chrome 浏览器

**测试目的：** 验证 Chrome 浏览器兼容性  
**测试步骤：**

1. 在 Chrome 浏览器中打开组件
2. 测试所有功能
3. 检查是否有问题

**期望结果：**

- 所有功能正常
- 样式正确

**测试类型：** 人工测试

---

#### 测试用例 5.1.2：Safari 浏览器

**测试目的：** 验证 Safari 浏览器兼容性  
**测试步骤：**

1. 在 Safari 浏览器中打开组件
2. 测试所有功能
3. 检查是否有问题

**期望结果：**

- 所有功能正常
- 样式正确

**测试类型：** 人工测试

---

#### 测试用例 5.1.3：Firefox 浏览器

**测试目的：** 验证 Firefox 浏览器兼容性  
**测试步骤：**

1. 在 Firefox 浏览器中打开组件
2. 测试所有功能
3. 检查是否有问题

**期望结果：**

- 所有功能正常
- 样式正确

**测试类型：** 人工测试

---

## 6. 测试总结

### 6.1 测试覆盖率

- 基础功能：100%
- 滚动方向：100%
- 滚动条样式：100%
- 滚动事件：100%
- 滚动按钮：100%
- Ref 方法：100%
- 吸附滚动：100%
- 边界条件：100%

### 6.2 已知问题

暂无已知问题

### 6.3 待优化项

- 性能测试需要更多场景
- 浏览器兼容性测试需要自动化
