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

﻿# PisellSingleSelect 组件测试用例文档

## 测试概览

本文档列出 PisellSingleSelect 组件的所有测试用例点，包括功能测试、交互测试、边界测试等。

**测试范围**：

- 组件渲染
- 状态切换
- 单选功能
- 搜索与过滤
- 校验逻辑
- 事件回调
- 边界情况处理

---

## 一、基础渲染测试

### 1.1 三种状态渲染

| 测试项   | 测试步骤                                    | 预期结果                          | 测试类型 |
|-------|-----------------------------------------|-------------------------------|------|
| 编辑态渲染 | 传入 `options` 和 `value`                  | 渲染 Ant Design Select 组件，显示选中值 | 自动化  |
| 只读态渲染 | 设置 `readOnly={true}`，传入 `value="apple"` | 渲染纯文本 "苹果"                    | 自动化  |
| 禁用态渲染 | 设置 `disabled={true}`，传入 `value="apple"` | 渲染禁用的 Select                  | 自动化  |

### 1.2 空值渲染

| 测试项    | 测试步骤                              | 预期结果                 | 测试类型 |
|--------|-----------------------------------|----------------------|------|
| 空值默认显示 | `readOnly={true}`, `value={null}` | 显示 "-"               | 自动化  |
| 编辑态空值  | `value={null}`                    | 输入框为空，显示 placeholder | 人工   |

### 1.3 标签与辅助文本

| 测试项    | 测试步骤                                | 预期结果          | 测试类型 |
|--------|-------------------------------------|---------------|------|
| 标签显示   | 设置 `label="选择项"`                    | 显示标签文本        | 自动化  |
| 必填标记   | 设置 `label="选择项"`, `required={true}` | 标签后显示红色 *     | 自动化  |
| 辅助文本   | 设置 `helperText="提示文本"`              | 在下方显示辅助文本     | 自动化  |
| 错误文本   | 设置 `error={true}`, `errorText="错误"` | 显示红色错误文本      | 自动化  |
| 错误覆盖辅助 | 同时设置 helperText 和 errorText         | 只显示 errorText | 自动化  |

---

## 二、受控与非受控模式测试

### 2.1 受控模式

| 测试项    | 测试步骤                            | 预期结果                | 测试类型 |
|--------|---------------------------------|---------------------|------|
| 受控模式基础 | 传入 `value="apple"` 和 `onChange` | 值由外部控制，onChange 被调用 | 自动化  |
| 受控模式更新 | 外部修改 value 从 "apple" 到 "banana" | 组件显示 "香蕉"           | 自动化  |
| 受控模式选择 | 在下拉框中选择新选项                      | onChange 被调用，参数正确   | 自动化  |

### 2.2 非受控模式

| 测试项     | 测试步骤                      | 预期结果         | 测试类型 |
|---------|---------------------------|--------------|------|
| 非受控模式基础 | 传入 `defaultValue="apple"` | 初始显示 "苹果"    | 自动化  |
| 非受控模式选择 | 在下拉框中选择新选项                | 内部状态更新，显示新选项 | 人工   |
| 非受控模式独立 | 不传入 onChange              | 组件正常工作，不报错   | 人工   |

---

## 三、单选功能测试

### 3.1 基础选择

| 测试项         | 测试步骤                   | 预期结果                             | 测试类型 |
|-------------|------------------------|----------------------------------|------|
| 点击触发器       | 点击选择框                  | 展开下拉列表                           | 人工   |
| 选择选项        | 点击某个选项                 | 选中该选项，下拉框关闭                      | 人工   |
| onChange 回调 | 选择选项                   | onChange 被调用，参数为 (value, option) | 自动化  |
| 选项禁用        | 选项设置 `disabled={true}` | 该选项不可选择                          | 人工   |

### 3.2 清空功能

| 测试项    | 测试步骤                          | 预期结果                  | 测试类型 |
|--------|-------------------------------|-----------------------|------|
| 清空按钮显示 | `allowClear={true}`，有值时 hover | 显示清空按钮                | 人工   |
| 点击清空   | 点击清空按钮                        | 值变为 null，onChange 被调用 | 自动化  |
| 清空后重选  | 清空后再次选择                       | 可以正常选择                | 人工   |

---

## 四、搜索与过滤测试

### 4.1 基础搜索

| 测试项   | 测试步骤                | 预期结果               | 测试类型 |
|-------|---------------------|--------------------|------|
| 显示搜索框 | `showSearch={true}` | 下拉框内显示搜索输入框        | 人工   |
| 搜索输入  | 输入搜索关键词             | 选项列表实时过滤           | 人工   |
| 搜索防抖  | 快速输入多个字符            | 300ms 后触发 onSearch | 自动化  |
| 清空搜索  | 删除搜索文本              | 显示所有选项             | 人工   |
| 无匹配结果 | 输入不存在的关键词           | 显示 "无数据"           | 人工   |

### 4.2 自定义过滤

| 测试项    | 测试步骤                    | 预期结果         | 测试类型 |
|--------|-------------------------|--------------|------|
| 默认过滤逻辑 | 未设置 filterOption，搜索     | 按 label 模糊匹配 | 人工   |
| 自定义过滤  | 设置 filterOption，自定义匹配规则 | 按自定义规则过滤     | 人工   |
| 大小写不敏感 | 输入大写字母搜索                | 能匹配小写选项      | 人工   |

### 4.3 搜索回调

| 测试项         | 测试步骤              | 预期结果           | 测试类型 |
|-------------|-------------------|----------------|------|
| onSearch 触发 | 设置 onSearch，输入搜索词 | 防抖后触发回调，参数正确   | 自动化  |
| 远程搜索        | onSearch 中模拟请求    | 可以动态更新 options | 人工   |

---

## 五、状态与样式测试

### 5.1 禁用态

| 测试项      | 测试步骤              | 预期结果            | 测试类型 |
|----------|-------------------|-----------------|------|
| 禁用态样式    | `disabled={true}` | 组件呈现禁用样式（灰色）    | 人工   |
| 禁用态不可交互  | disabled，点击触发器    | 无法打开下拉框         | 自动化  |
| 禁用态不触发事件 | disabled，尝试操作     | onChange 等事件不触发 | 自动化  |

### 5.2 只读态

| 测试项     | 测试步骤                               | 预期结果          | 测试类型 |
|---------|------------------------------------|---------------|------|
| 只读态显示   | `readOnly={true}`, `value="apple"` | 显示选中选项的 label | 自动化  |
| 只读态图标   | 选项有 icon，只读态                       | 显示图标 + 文本     | 人工   |
| 只读态不可交互 | readOnly，点击                        | 无交互响应         | 人工   |

### 5.3 错误状态

| 测试项    | 测试步骤                             | 预期结果      | 测试类型 |
|--------|----------------------------------|-----------|------|
| 错误边框   | `error={true}`                   | 选择框边框变为红色 | 人工   |
| 错误文本显示 | `error={true}`, `errorText="错误"` | 显示红色错误文本  | 自动化  |
| 错误样式焦点 | error 状态下聚焦                      | 红色边框和焦点效果 | 人工   |

### 5.4 尺寸变体

| 测试项       | 测试步骤            | 预期结果                | 测试类型 |
|-----------|-----------------|---------------------|------|
| Small 尺寸  | `size="small"`  | 高度 32px，字号 14px     | 人工   |
| Medium 尺寸 | `size="medium"` | 高度 48px，字号 16px（默认） | 人工   |
| Large 尺寸  | `size="large"`  | 高度 56px，字号 18px     | 人工   |

---

## 六、键盘交互测试

### 6.1 键盘导航

| 测试项       | 测试步骤          | 预期结果      | 测试类型 |
|-----------|---------------|-----------|------|
| Tab 键聚焦   | 按 Tab 键       | 可以聚焦到选择框  | 人工   |
| Enter 打开  | 聚焦后按 Enter    | 展开下拉列表    | 人工   |
| 上下箭头      | 打开下拉后按上下箭头    | 高亮项上下移动   | 人工   |
| Enter 选择  | 高亮某项后按 Enter  | 选中该项，关闭下拉 | 人工   |
| Escape 关闭 | 打开下拉后按 Escape | 关闭下拉框     | 人工   |
| Tab 失焦    | 打开下拉后按 Tab    | 失焦并关闭下拉框  | 人工   |

---

## 七、事件回调测试

### 7.1 值变化事件

| 测试项         | 测试步骤 | 预期结果                  | 测试类型 |
|-------------|------|-----------------------|------|
| onChange 参数 | 选择选项 | 回调参数为 (value, option) | 自动化  |
| onChange 空值 | 清空选择 | 回调参数为 (null, null)    | 自动化  |

### 7.2 焦点事件

| 测试项     | 测试步骤             | 预期结果  | 测试类型 |
|---------|------------------|-------|------|
| onFocus | 设置 onFocus，点击选择框 | 回调被调用 | 自动化  |
| onBlur  | 设置 onBlur，点击外部   | 回调被调用 | 自动化  |

### 7.3 下拉框事件

| 测试项                     | 测试步骤     | 预期结果                 | 测试类型 |
|-------------------------|----------|----------------------|------|
| onDropdownVisibleChange | 打开/关闭下拉框 | 回调被调用，参数为 true/false | 人工   |

---

## 八、Ref 方法测试

### 8.1 Ref 方法

| 测试项          | 测试步骤                             | 预期结果         | 测试类型 |
|--------------|----------------------------------|--------------|------|
| focus()      | 调用 ref.current.focus()           | 组件获得焦点       | 自动化  |
| blur()       | 调用 ref.current.blur()            | 组件失去焦点       | 自动化  |
| getValue()   | 调用 ref.current.getValue()        | 返回当前值        | 自动化  |
| setValue()   | 调用 ref.current.setValue('apple') | 值更新为 "apple" | 自动化  |
| clearValue() | 调用 ref.current.clearValue()      | 值变为 null     | 自动化  |

---

## 九、样式定制测试

### 9.1 自定义样式

| 测试项       | 测试步骤                         | 预期结果      | 测试类型 |
|-----------|------------------------------|-----------|------|
| 自定义类名     | `className="custom-select"`  | 元素包含该类名   | 自动化  |
| 自定义 style | `style={{ width: 300 }}`     | 宽度为 300px | 自动化  |
| Token 样式  | 修改 tokens.ts 中的 Select Token | 全局样式生效    | 人工   |
| Less 样式   | 修改 Less 文件                   | 组件样式生效    | 人工   |

### 9.2 只读态样式

| 测试项    | 测试步骤        | 预期结果         | 测试类型 |
|--------|-------------|--------------|------|
| 只读态背景色 | readOnly 状态 | 背景色为 #F9FAFB | 人工   |
| 只读态边框  | readOnly 状态 | 边框为 #D0D5DD  | 人工   |
| 只读态图标  | 选项有 icon    | 图标正确显示       | 人工   |

---

## 十、边界情况测试

### 10.1 选项列表

| 测试项   | 测试步骤               | 预期结果          | 测试类型 |
|-------|--------------------|---------------|------|
| 空选项列表 | `options={[]}`     | 下拉框显示 "无数据"   | 人工   |
| 单个选项  | `options` 只有1项     | 正常显示和选择       | 人工   |
| 大量选项  | `options` 有 1000 项 | 下拉流畅，无卡顿      | 人工   |
| 选项值重复 | 两个选项 value 相同      | 能正确识别（建议提示错误） | 人工   |

### 10.2 特殊输入

| 测试项         | 测试步骤                  | 预期结果    | 测试类型 |
|-------------|-----------------------|---------|------|
| undefined 值 | `value={undefined}`   | 显示为空    | 人工   |
| null 值      | `value={null}`        | 显示为空    | 人工   |
| 不存在的值       | `value="nonexistent"` | 显示为空或该值 | 人工   |

---

## 十一、性能测试

### 11.1 渲染性能

| 测试项   | 测试步骤            | 预期结果        | 测试类型 |
|-------|-----------------|-------------|------|
| 初始渲染  | 渲染组件            | 渲染时间 < 50ms | 人工   |
| 值更新性能 | 频繁更新 value      | 无明显卡顿       | 人工   |
| 表格渲染  | 表格中渲染 1000 行只读态 | 滚动流畅        | 人工   |

### 11.2 搜索性能

| 测试项  | 测试步骤          | 预期结果         | 测试类型 |
|------|---------------|--------------|------|
| 搜索防抖 | 快速输入多个字符      | 300ms 后才触发过滤 | 人工   |
| 搜索过滤 | 搜索大量选项（1000+） | 过滤流畅，无卡顿     | 人工   |

---

## 十二、可访问性测试

### 12.1 ARIA 属性

| 测试项              | 测试步骤                 | 预期结果                      | 测试类型 |
|------------------|----------------------|---------------------------|------|
| aria-label       | 设置 `aria-label="选择"` | 元素包含该属性                   | 人工   |
| aria-required    | `required={true}`    | 元素包含 aria-required="true" | 人工   |
| aria-invalid     | `error={true}`       | 元素包含 aria-invalid="true"  | 人工   |
| aria-describedby | `helperText` 存在      | 元素关联描述文本                  | 人工   |

### 12.2 键盘导航

| 测试项    | 测试步骤      | 预期结果      | 测试类型 |
|--------|-----------|-----------|------|
| 完整键盘操作 | 仅使用键盘完成选择 | 可以完成所有操作  | 人工   |
| 焦点管理   | Tab 切换焦点  | 焦点顺序正确    | 人工   |
| 屏幕阅读器  | 使用屏幕阅读器   | 正确播报角色和状态 | 人工   |

---

## 十三、集成测试

### 13.1 表单集成

| 测试项          | 测试步骤                       | 预期结果    | 测试类型 |
|--------------|----------------------------|---------|------|
| Form.Item 包裹 | 在 Ant Design Form.Item 中使用 | 正常工作    | 人工   |
| 表单提交         | Form 提交时获取值                | 值正确     | 人工   |
| 表单重置         | 调用 form.resetFields()      | 值重置为初始值 | 人工   |
| 表单校验         | Form 提交时校验                 | 必填规则生效  | 人工   |

### 13.2 表格集成

| 测试项   | 测试步骤                 | 预期结果      | 测试类型 |
|-------|----------------------|-----------|------|
| 表格单元格 | 在 Table 的 render 中使用 | 正确显示      | 人工   |
| 只读态展示 | `readOnly` 在表格中      | 纯文本展示，性能好 | 人工   |
| 大量数据  | 表格 1000 行，每行一个组件     | 滚动流畅      | 人工   |

---

## 十四、兼容性测试

### 14.1 浏览器兼容

| 测试项     | 测试环境         | 预期结果 | 测试类型 |
|---------|--------------|------|------|
| Chrome  | Chrome 120+  | 功能正常 | 人工   |
| Firefox | Firefox 120+ | 功能正常 | 人工   |
| Safari  | Safari 17+   | 功能正常 | 人工   |
| Edge    | Edge 120+    | 功能正常 | 人工   |

### 14.2 移动端

| 测试项            | 测试环境       | 预期结果    | 测试类型 |
|----------------|------------|---------|------|
| iOS Safari     | iOS 设备     | 触摸交互正常  | 人工   |
| Android Chrome | Android 设备 | 触摸交互正常  | 人工   |
| 触摸展开           | 移动端点击      | 下拉框正常展开 | 人工   |

---

## 十五、边界与异常测试

### 15.1 异常 Props

| 测试项          | 测试步骤           | 预期结果      | 测试类型 |
|--------------|----------------|-----------|------|
| 缺少 options   | 不传入 options    | 显示空下拉框或提示 | 人工   |
| options 为空数组 | `options={[]}` | 显示 "无数据"  | 人工   |
| 错误的 value 类型 | value 类型与选项不匹配 | 不报错，显示为空  | 人工   |

### 15.2 快速操作

| 测试项   | 测试步骤       | 预期结果          | 测试类型 |
|-------|------------|---------------|------|
| 快速点击  | 快速连续点击触发器  | 不报错，正常响应      | 人工   |
| 快速搜索  | 快速输入大量字符   | 防抖正常，不卡顿      | 人工   |
| 快速切换值 | 快速连续选择不同选项 | onChange 正确触发 | 人工   |

---

## 十六、LowCode 集成测试

### 16.1 Meta 配置

| 测试项      | 测试步骤                      | 预期结果    | 测试类型 |
|----------|---------------------------|---------|------|
| 组件拖拽     | 从物料面板拖拽组件                 | 正确添加到画布 | 人工   |
| Props 配置 | 在属性面板修改 props             | 组件实时更新  | 人工   |
| 选项配置     | 使用 ArraySetter 配置 options | 选项正确显示  | 人工   |
| 事件绑定     | 绑定 onChange 事件            | 事件正确触发  | 人工   |

### 16.2 Snippets

| 测试项   | 测试步骤          | 预期结果      | 测试类型 |
|-------|---------------|-----------|------|
| 基础模板  | 拖拽"单选下拉（基础）"  | 组件正确渲染    | 人工   |
| 带标签模板 | 拖拽"单选下拉（带标签）" | 显示标签和必填标记 | 人工   |
| 带搜索模板 | 拖拽"单选下拉（带搜索）" | 搜索功能正常    | 人工   |
| 只读模板  | 拖拽"单选下拉（只读）"  | 只读态正确显示   | 人工   |

---

## Bug 汇总

### 待修复的 Bug

| Bug ID | 描述 | 优先级 | 状态 | 发现时间 |
|--------|----|-----|----|------|
| -      | -  | -   | -  | -    |

### 已修复的 Bug

| Bug ID | 描述 | 修复方案 | 修复时间 |
|--------|----|------|------|
| -      | -  | -    | -    |

---

## 测试统计

| 类别    | 总数  | 已通过 | 未通过 | 待测试 |
|-------|-----|-----|-----|-----|
| 自动化测试 | 25  | 0   | 0   | 25  |
| 人工测试  | 60+ | 0   | 0   | 60+ |
| 总计    | 85+ | 0   | 0   | 85+ |

---

## 测试环境

**开发环境**：

- Node.js: 18+
- React: 18+
- Ant Design: 5.x
- 测试框架: Vitest + React Testing Library

**测试浏览器**：

- Chrome 120+
- Firefox 120+
- Safari 17+
- Edge 120+

---

## 测试说明

**自动化测试**：

- 使用 Vitest + React Testing Library
- 测试文件：`PisellSingleSelect.test.tsx`
- 运行命令：`pnpm test pisellSingleSelect`

**人工测试**：

- 使用 Storybook 进行图形化测试
- 测试文件：`PisellSingleSelect.stories.tsx`
- 运行命令：`pnpm storybook`

**测试注意事项**：

1. 每次修改代码后都要运行自动化测试
2. 人工测试在 Storybook 中逐个场景验证
3. Bug 及时记录在 Bug 汇总模块
4. 测试完成后更新测试统计表
5. 重点测试搜索防抖功能
6. 重点测试只读态的正确显示
