@pisell/private-materials 6.6.8 → 6.6.9

package/dist/es/pro/Selector/TEST.md

@@ -0,0 +1,1029 @@
+# Selector 组件测试计划文档
+
+## 1. 测试概述
+
+### 1.1 组件信息
+
+| 项目 | 内容 |
+|------|------|
+| 组件名称 | Selector |
+| 组件路径 | `packages/private-materials/src/pro/Selector` |
+| 组件类型 | React 函数组件 (forwardRef) |
+| 依赖 Hook | `useSelectionController` |
+| 子组件 | `CardItem`、`NumericStepper` |
+
+### 1.2 测试范围
+
+- ✅ **核心功能**：选择、切换、数量控制、校验
+- ✅ **UI 渲染**：不同变体、布局、样式
+- ✅ **交互行为**：点击、切换、输入
+- ✅ **边界条件**：空数据、极端值、异常输入
+- ✅ **集成场景**：与 SelectorGroup 组合使用
+
+### 1.3 测试策略
+
+| 测试类型 | 工具 | 优先级 | 覆盖率目标 |
+|---------|------|--------|-----------|
+| 单元测试 | Vitest + RTL | P0 | 80%+ |
+| 集成测试 | Vitest + RTL | P1 | 70%+ |
+| 交互测试 | RTL + user-event | P1 | 60%+ |
+| 快照测试 | Vitest | P2 | 核心组件 |
+| 可视化测试 | Storybook | P1 | 核心场景 |
+| E2E 测试 | Playwright (可选) | P2 | 关键流程 |
+
+---
+
+## 2. 测试环境配置
+
+### 2.1 测试工具链
+
+```typescript
+// 测试框架
+- Vitest: ^1.6.0
+- @testing-library/react: ^12.1.5
+- @testing-library/user-event: ^14.6.1
+- @testing-library/jest-dom: ^5.16.5
+
+// 测试环境
+- jsdom: ^22.1.0 (浏览器环境模拟)
+```
+
+### 2.2 Mock 配置
+
+参考 `src/test/setup.ts` 中的 Mock 配置：
+- ✅ Ant Design 组件 Mock
+- ✅ 国际化 locales Mock
+- ✅ EngineContext Mock
+- ✅ CSS Modules Mock
+
+### 2.3 测试辅助函数
+
+```typescript
+// 测试工具函数示例
+export const renderSelector = (props: Partial<SelectorProps>) => {
+  return render(<Selector {...defaultProps} {...props} />);
+};
+
+export const createMockDataSource = (count: number) => {
+  return Array.from({ length: count }, (_, i) => ({
+    id: i + 1,
+    value: i + 1,
+    label: `选项${i + 1}`,
+    title: `选项${i + 1}`,
+  }));
+};
+```
+
+---
+
+## 3. 测试数据准备
+
+### 3.1 基础测试数据
+
+```typescript
+// 最小数据集
+export const minimalDataSource = [
+  { id: 1, value: 1, label: '选项1', title: '选项1' },
+  { id: 2, value: 2, label: '选项2', title: '选项2' },
+];
+
+// 标准数据集
+export const standardDataSource = [
+  { id: 1, value: 1, label: '选项1', title: '选项1' },
+  { id: 2, value: 2, label: '选项2', title: '选项2' },
+  { id: 3, value: 3, label: '选项3', title: '选项3' },
+  { id: 4, value: 4, label: '选项4', title: '选项4' },
+  { id: 5, value: 5, label: '选项5', title: '选项5' },
+];
+
+// 带数量限制的数据集
+export const quantityDataSource = [
+  { 
+    id: 1, 
+    value: 1, 
+    label: '选项1', 
+    title: '选项1',
+    ruleConfig: { min: 1, max: 10 }
+  },
+  { 
+    id: 2, 
+    value: 2, 
+    label: '选项2', 
+    title: '选项2',
+    ruleConfig: { min: 0, max: 5 }
+  },
+];
+
+// 带互斥规则的数据集
+// 互斥规则说明：
+// - 选项1、2、3 属于互斥组1，同一组内只能选择一个
+// - 选项4、5、6 属于互斥组2，同一组内只能选择一个
+// 使用时需要在 ruleConfig 中配置：mutex: [[1, 2, 3], [4, 5, 6]]
+export const mutexDataSource = [
+  { id: 1, value: 1, label: '选项1（互斥组1）', title: '选项1' },
+  { id: 2, value: 2, label: '选项2（互斥组1）', title: '选项2' },
+  { id: 3, value: 3, label: '选项3（互斥组1）', title: '选项3' },
+  { id: 4, value: 4, label: '选项4（互斥组2）', title: '选项4' },
+  { id: 5, value: 5, label: '选项5（互斥组2）', title: '选项5' },
+  { id: 6, value: 6, label: '选项6（互斥组2）', title: '选项6' },
+];
+
+// 互斥规则配置示例（用于测试）
+export const mutexRuleConfig = {
+  mutex: [
+    [1, 2, 3],  // 互斥组1：选项1、2、3 只能选一个
+    [4, 5, 6],  // 互斥组2：选项4、5、6 只能选一个
+  ],
+};
+```
+
+### 3.2 边界测试数据
+
+```typescript
+// 空数据
+export const emptyDataSource: OptionItem[] = [];
+
+// 单条数据
+export const singleItemDataSource = [
+  { id: 1, value: 1, label: '唯一选项', title: '唯一选项' },
+];
+
+// 大量数据（性能测试）
+export const largeDataSource = Array.from({ length: 1000 }, (_, i) => ({
+  id: i + 1,
+  value: i + 1,
+  label: `选项${i + 1}`,
+  title: `选项${i + 1}`,
+}));
+
+// 异常数据
+export const invalidDataSource = [
+  { id: null, value: undefined, label: '', title: '' }, // 缺失必填字段
+  { id: 2, value: 2, label: '选项2', title: '选项2' },
+];
+```
+
+### 3.3 默认 Props
+
+```typescript
+export const defaultSelectorProps: Partial<SelectorProps> = {
+  id: 'test-selector',
+  title: '测试标题',
+  dataSource: standardDataSource,
+  mode: 'single',
+  valueType: 'primitive',
+  fieldNames: { value: 'value', label: 'label' },
+};
+```
+
+---
+
+## 4. 功能测试用例
+
+### 4.1 基础渲染测试
+
+| 用例ID | 测试场景 | 测试步骤 | 预期结果 | 优先级 |
+|--------|---------|---------|---------|--------|
+| TC-F-001 | 组件正常渲染 | 渲染组件，传入基础 props | 组件成功渲染，无报错 | P0 |
+| TC-F-002 | 渲染选项列表 | 传入 dataSource，检查选项数量 | 所有选项正确渲染 | P0 |
+| TC-F-003 | 空数据源渲染 | 传入空数组 dataSource | 显示空状态或空列表，无报错 | P1 |
+| TC-F-004 | 自定义 fieldNames | 传入自定义 fieldNames | 选项使用自定义字段映射 | P1 |
+
+**测试代码示例**：
+```typescript
+describe('基础渲染测试', () => {
+  test('TC-F-001: 组件正常渲染', () => {
+    const { container } = render(<Selector {...defaultProps} />);
+    expect(container).toBeInTheDocument();
+  });
+
+  test('TC-F-002: 渲染选项列表', () => {
+    const { getAllByRole } = render(
+      <Selector dataSource={standardDataSource} />
+    );
+    const radios = getAllByRole('radio');
+    expect(radios).toHaveLength(standardDataSource.length);
+  });
+});
+```
+
+### 4.2 单选模式测试
+
+| 用例ID | 测试场景 | 测试步骤 | 预期结果 | 优先级 |
+|--------|---------|---------|---------|--------|
+| TC-S-001 | 单选模式渲染 | mode='single'，检查使用 Radio | 使用 Radio 组件 | P0 |
+| TC-S-002 | 选择选项 | 点击未选中选项 | 选项被选中，onChange 触发 | P0 |
+| TC-S-003 | 取消选择 | 点击已选中选项 | 选项被取消，值变为 undefined | P0 |
+| TC-S-004 | 切换选择 | 选择新选项 | 旧选项自动取消，新选项选中 | P0 |
+| TC-S-005 | 原始值返回 | valueType='primitive' | onChange 返回原始值 | P0 |
+| TC-S-006 | 对象值返回 | valueType='object' | onChange 返回对象值 | P0 |
+
+**测试代码示例**：
+```typescript
+describe('单选模式测试', () => {
+  test('TC-S-002: 选择选项', async () => {
+    const user = userEvent.setup();
+    const handleChange = vi.fn();
+    
+    const { getAllByRole } = render(
+      <Selector
+        dataSource={standardDataSource}
+        mode="single"
+        valueType="primitive"
+        onChange={handleChange}
+      />
+    );
+    
+    const radios = getAllByRole('radio');
+    await user.click(radios[0]);
+    
+    expect(handleChange).toHaveBeenCalledWith(1);
+    expect(radios[0]).toBeChecked();
+  });
+});
+```
+
+### 4.3 多选模式测试
+
+| 用例ID | 测试场景 | 测试步骤 | 预期结果 | 优先级 |
+|--------|---------|---------|---------|--------|
+| TC-M-001 | 多选模式渲染 | mode='multiple'，检查使用 Checkbox | 使用 Checkbox 组件 | P0 |
+| TC-M-002 | 多选选项 | 依次选择多个选项 | 多个选项同时选中 | P0 |
+| TC-M-003 | 取消单个选项 | 点击已选中选项 | 仅该选项取消，其他保持 | P0 |
+| TC-M-004 | 原始值数组返回 | valueType='primitive' | onChange 返回数组 | P0 |
+| TC-M-005 | 对象值数组返回 | valueType='object' | onChange 返回对象数组 | P0 |
+
+### 4.4 数量选择测试
+
+| 用例ID | 测试场景 | 测试步骤 | 预期结果 | 优先级 |
+|--------|---------|---------|---------|--------|
+| TC-Q-001 | 数量选择器显示 | 选项 max > 1，valueType='object' | 显示数量选择器 | P0 |
+| TC-Q-002 | 数量修改 | 修改数量值 | onChange 触发，值包含 quantity | P0 |
+| TC-Q-003 | 数量为 0 自动取消 | 将数量调为 0 | 选项自动取消选择 | P0 |
+| TC-Q-004 | 数量限制 min | 数量小于 min | 显示错误提示 | P1 |
+| TC-Q-005 | 数量限制 max | 数量大于 max | 显示错误提示 | P1 |
+| TC-Q-006 | 选项级数量限制 | 不同选项不同限制 | 各自限制生效 | P1 |
+
+### 4.5 校验规则测试
+
+| 用例ID | 测试场景 | 测试步骤 | 预期结果 | 优先级 |
+|--------|---------|---------|---------|--------|
+| TC-V-001 | required 必选校验 | required=1，未选择 | validate 失败，显示错误 | P0 |
+| TC-V-002 | min 最小数量校验 | min=2，选择少于 2 个 | validate 失败 | P0 |
+| TC-V-003 | max 最大数量校验 | max=3，选择超过 3 个 | validate 失败 | P0 |
+| TC-V-004 | mutex 互斥组校验 | 选择同组多个选项 | 自动取消同组其他选项 | P0 |
+| TC-V-005 | customValidator 自定义校验 | 传入自定义校验器 | 校验器逻辑生效 | P1 |
+| TC-V-006 | 自动校验 | autoValidate=true | 选择时自动校验 | P1 |
+
+**测试代码示例**：
+```typescript
+describe('校验规则测试', () => {
+  test('TC-V-001: required 必选校验', async () => {
+    const ref = React.createRef<any>();
+    
+    render(
+      <Selector
+        ref={ref}
+        dataSource={standardDataSource}
+        ruleConfig={{ required: 1 }}
+      />
+    );
+    
+    await expect(ref.current.validate()).rejects.toBeDefined();
+    const errors = ref.current.getErrors();
+    expect(errors.some(e => e.type === 'required')).toBe(true);
+  });
+});
+```
+
+### 4.6 Ref 方法测试
+
+| 用例ID | 测试场景 | 测试步骤 | 预期结果 | 优先级 |
+|--------|---------|---------|---------|--------|
+| TC-R-001 | validate 方法 | 调用 ref.validate() | 返回 Promise，执行校验 | P0 |
+| TC-R-002 | getErrors 方法 | 调用 ref.getErrors() | 返回错误数组 | P0 |
+| TC-R-003 | reset 方法 | 调用 ref.reset() | 重置为 defaultValue | P0 |
+| TC-R-004 | clear 方法 | 调用 ref.clear() | 清空所有选择 | P0 |
+
+---
+
+## 5. UI/交互测试用例
+
+### 5.1 布局测试
+
+| 用例ID | 测试场景 | 测试步骤 | 预期结果 | 优先级 |
+|--------|---------|---------|---------|--------|
+| TC-U-001 | 默认布局 | 不传 grid | 垂直列表布局 | P1 |
+| TC-U-002 | 网格布局 2 列 | grid={{ columns: 2 }} | 选项呈 2 列排列 | P1 |
+| TC-U-003 | 网格布局 3 列 | grid={{ columns: 3 }} | 选项呈 3 列排列 | P1 |
+| TC-U-004 | 网格间距 | grid={{ gutter: 24 }} | 选项间距正确 | P2 |
+| TC-U-005 | 网格对齐 | grid={{ align: 'middle' }} | 对齐方式生效 | P2 |
+
+### 5.2 样式变体测试
+
+| 用例ID | 测试场景 | 测试步骤 | 预期结果 | 优先级 |
+|--------|---------|---------|---------|--------|
+| TC-SV-001 | default 变体 | variant='default' | 默认 Radio/Checkbox | P1 |
+| TC-SV-002 | card 变体 | variant='card' | 渲染卡片样式 | P1 |
+| TC-SV-003 | select 变体 | variant='select' | 渲染 Select 下拉 | P1 |
+| TC-SV-004 | 卡片布局 vertical | item={{ layout: 'vertical' }} | 垂直布局 | P1 |
+| TC-SV-005 | 卡片布局 horizontal | item={{ layout: 'horizontal' }} | 水平布局 | P1 |
+| TC-SV-006 | 选中态样式 filled | item={{ selectedTypeVariant: 'filled' }} | 填充样式 | P1 |
+| TC-SV-007 | 选中态样式 cornered | item={{ selectedTypeVariant: 'cornered' }} | 角标样式 | P1 |
+
+### 5.3 标题与提示测试
+
+| 用例ID | 测试场景 | 测试步骤 | 预期结果 | 优先级 |
+|--------|---------|---------|---------|--------|
+| TC-T-001 | 标题显示 | 传入 title | 标题正确显示 | P1 |
+| TC-T-002 | 标题隐藏 | titleProps={{ visible: false }} | 标题隐藏 | P1 |
+| TC-T-003 | 自定义标题 | titleProps={{ title: { text: '自定义' } }} | 显示自定义文本 | P1 |
+| TC-T-004 | 提示信息 | titleProps={{ tip: { text: '提示' } }} | 提示正确显示 | P1 |
+| TC-T-005 | 自动提示 | ruleConfig 有 min/max | 自动生成提示文本 | P1 |
+| TC-T-006 | 必选标签 | ruleConfig={{ required: 1 }} | 显示必选标签 | P1 |
+| TC-T-007 | 错误信息显示 | 校验失败 | 错误信息显示 | P0 |
+
+### 5.4 交互测试
+
+| 用例ID | 测试场景 | 测试步骤 | 预期结果 | 优先级 |
+|--------|---------|---------|---------|--------|
+| TC-I-001 | 点击选项选择 | 点击未选中选项 | 选项选中，状态更新 | P0 |
+| TC-I-002 | 点击已选项取消 | 点击已选中选项 | 选项取消，状态更新 | P0 |
+| TC-I-003 | 禁用选项不可点击 | 点击 disabled 选项 | 无响应，状态不变 | P1 |
+| TC-I-004 | 组件禁用 | disabled=true | 所有选项禁用 | P1 |
+| TC-I-005 | 数量步进器交互 | 点击 +/- 按钮 | 数量正确增减 | P0 |
+| TC-I-006 | 快速连续操作 | 快速点击多个选项 | 状态正确，无异常 | P1 |
+
+**测试代码示例**：
+```typescript
+describe('交互测试', () => {
+  test('TC-I-001: 点击选项选择', async () => {
+    const user = userEvent.setup();
+    const handleChange = vi.fn();
+    
+    const { getAllByRole } = render(
+      <Selector
+        dataSource={standardDataSource}
+        mode="single"
+        onChange={handleChange}
+      />
+    );
+    
+    const radios = getAllByRole('radio');
+    await user.click(radios[0]);
+    
+    expect(handleChange).toHaveBeenCalled();
+    expect(radios[0]).toBeChecked();
+  });
+});
+```
+
+---
+
+## 6. 边界与异常测试用例
+
+### 6.1 数据边界测试
+
+| 用例ID | 测试场景 | 测试步骤 | 预期结果 | 优先级 |
+|--------|---------|---------|---------|--------|
+| TC-B-001 | 空数据源 | dataSource=[] | 正常渲染，不报错 | P1 |
+| TC-B-002 | 单条数据 | dataSource 只有 1 条 | 正常渲染 | P1 |
+| TC-B-003 | 大量数据 | dataSource 1000+ 条 | 性能可接受，正常渲染 | P2 |
+| TC-B-004 | 重复 value | 多个选项相同 value | 处理正确或提示错误 | P1 |
+| TC-B-005 | null/undefined 值 | value 为 null/undefined | 处理正确，不报错 | P1 |
+
+### 6.2 值边界测试
+
+| 用例ID | 测试场景 | 测试步骤 | 预期结果 | 优先级 |
+|--------|---------|---------|---------|--------|
+| TC-B-006 | 数量为 0 | quantity=0 | 选项取消或保持 | P1 |
+| TC-B-007 | 数量为负数 | quantity=-1 | 处理正确，不报错 | P1 |
+| TC-B-008 | 数量超大值 | quantity=999999 | 受 max 限制或处理正确 | P1 |
+| TC-B-009 | 无效 value | value 不在 dataSource | 处理正确，不报错 | P1 |
+
+### 6.3 异常场景测试
+
+| 用例ID | 测试场景 | 测试步骤 | 预期结果 | 优先级 |
+|--------|---------|---------|---------|--------|
+| TC-E-001 | onChange 抛出异常 | onChange 中 throw Error | 不影响组件状态 | P2 |
+| TC-E-002 | 校验器抛出异常 | customValidator throw | 错误正确处理 | P1 |
+| TC-E-003 | 数据源动态变化 | dataSource 从有到无 | 状态正确处理 | P1 |
+| TC-E-004 | 值动态变化 | value 外部变更 | 状态同步更新 | P0 |
+| TC-E-005 | 规则动态变化 | ruleConfig 变更 | 重新校验生效 | P1 |
+
+---
+
+## 7. 性能测试用例
+
+### 7.1 渲染性能测试
+
+| 用例ID | 测试场景 | 测试步骤 | 预期结果 | 优先级 |
+|--------|---------|---------|---------|--------|
+| TC-P-001 | 100 选项渲染 | 渲染 100 个选项 | 渲染时间 < 500ms | P2 |
+| TC-P-002 | 1000 选项渲染 | 渲染 1000 个选项 | 渲染时间 < 2000ms | P2 |
+| TC-P-003 | 大数据集交互 | 1000 选项中选择 | 交互响应 < 100ms | P2 |
+
+### 7.2 内存测试
+
+| 用例ID | 测试场景 | 测试步骤 | 预期结果 | 优先级 |
+|--------|---------|---------|---------|--------|
+| TC-P-004 | 内存泄漏检测 | 创建销毁 100 次 | 无内存泄漏 | P2 |
+| TC-P-005 | 大数据集内存 | 1000 选项内存占用 | 内存占用 < 50MB | P2 |
+
+---
+
+## 8. 可访问性测试用例
+
+### 8.1 键盘导航测试
+
+| 用例ID | 测试场景 | 测试步骤 | 预期结果 | 优先级 |
+|--------|---------|---------|---------|--------|
+| TC-A-001 | Tab 键导航 | 按 Tab 切换焦点 | 焦点正确切换 | P1 |
+| TC-A-002 | Space/Enter 选择 | 焦点在选项时按 Space | 选项选中/取消 | P1 |
+| TC-A-003 | 方向键导航 | 使用方向键切换 | 选项正确切换 | P1 |
+
+### 8.2 ARIA 与语义化测试
+
+> **说明**：屏幕阅读器测试主要用于验证组件对视觉障碍用户的可访问性。在单元测试中，我们主要通过检查 ARIA 属性和语义化 HTML 来确保可访问性。
+
+| 用例ID | 测试场景 | 测试步骤 | 预期结果 | 优先级 |
+|--------|---------|---------|---------|--------|
+| TC-A-004 | ARIA 标签检查 | 检查 Radio/Checkbox 的 aria-label | 有正确的 ARIA 标签 | P1 |
+| TC-A-005 | 选中状态语义 | 检查 checked 状态 | aria-checked 正确反映状态 | P1 |
+| TC-A-006 | 禁用状态语义 | 检查 disabled 属性 | aria-disabled 正确 | P1 |
+| TC-A-007 | 错误信息语义 | 校验失败时检查 | 错误信息有适当的 ARIA 属性 | P2 |
+| TC-A-008 | 表单关联 | 检查 label 关联 | label 与 input 正确关联 | P1 |
+
+**测试代码示例**：
+```typescript
+describe('ARIA 可访问性测试', () => {
+  test('TC-A-004: ARIA 标签检查', () => {
+    const { getAllByRole } = render(
+      <Selector
+        dataSource={standardDataSource}
+        mode="single"
+        title="选择选项"
+      />
+    );
+    
+    const radios = getAllByRole('radio');
+    // Radio 组件应该自动处理 ARIA 属性
+    radios.forEach((radio, index) => {
+      expect(radio).toHaveAttribute('aria-label', standardDataSource[index].label);
+    });
+  });
+
+  test('TC-A-005: 选中状态语义', async () => {
+    const user = userEvent.setup();
+    const { getAllByRole } = render(
+      <Selector
+        dataSource={standardDataSource}
+        mode="single"
+      />
+    );
+    
+    const radios = getAllByRole('radio');
+    await user.click(radios[0]);
+    
+    expect(radios[0]).toHaveAttribute('aria-checked', 'true');
+    expect(radios[1]).toHaveAttribute('aria-checked', 'false');
+  });
+});
+```
+
+**注意**：
+- ✅ **单元测试中的可访问性测试**：主要检查 ARIA 属性和语义化 HTML，这是自动化的、可执行的
+- ⚠️ **真实屏幕阅读器测试**：需要使用真实屏幕阅读器软件（如 NVDA、JAWS、VoiceOver）进行人工测试，属于 E2E 测试范畴
+- 💡 **实际建议**：对于内部组件库，单元测试中的 ARIA 检查已足够；对于面向公众的产品，建议进行真实屏幕阅读器测试
+
+---
+
+## 9. 测试用例执行清单
+
+### 9.1 测试用例分类统计
+
+| 类别 | 用例数量 | P0 | P1 | P2 | 完成状态 |
+|------|---------|-----|-----|-----|---------|
+| 基础渲染 | 4 | 2 | 2 | 0 | ⬜ |
+| 单选模式 | 6 | 6 | 0 | 0 | ⬜ |
+| 多选模式 | 5 | 5 | 0 | 0 | ⬜ |
+| 数量选择 | 6 | 2 | 4 | 0 | ⬜ |
+| 校验规则 | 6 | 3 | 3 | 0 | ⬜ |
+| Ref 方法 | 4 | 4 | 0 | 0 | ⬜ |
+| UI 布局 | 5 | 0 | 3 | 2 | ⬜ |
+| 样式变体 | 7 | 0 | 7 | 0 | ⬜ |
+| 标题提示 | 7 | 1 | 6 | 0 | ⬜ |
+| 交互测试 | 6 | 2 | 4 | 0 | ⬜ |
+| 边界测试 | 9 | 0 | 6 | 3 | ⬜ |
+| 异常测试 | 5 | 1 | 4 | 0 | ⬜ |
+| 性能测试 | 5 | 0 | 0 | 5 | ⬜ |
+| 可访问性 | 8 | 0 | 8 | 0 | ⬜ |
+| Storybook 测试 | 16 | 5 | 10 | 1 | ⬜ |
+| **总计** | **93** | **31** | **51** | **11** | **0%** |
+
+### 9.2 测试执行优先级
+
+#### Phase 1: 核心功能 (P0) - 31 个用例
+- [ ] 基础渲染测试（2）
+- [ ] 单选模式测试（6）
+- [ ] 多选模式测试（5）
+- [ ] 数量选择基础（2）
+- [ ] 校验规则核心（3）
+- [ ] Ref 方法测试（4）
+- [ ] 标题错误显示（1）
+- [ ] 交互核心（2）
+- [ ] 值同步更新（1）
+- [ ] Storybook 核心测试（5）
+
+#### Phase 2: 重要功能 (P1) - 48 个用例
+- [ ] 基础渲染扩展（2）
+- [ ] 数量选择扩展（4）
+- [ ] 校验规则扩展（3）
+- [ ] UI 布局测试（3）
+- [ ] 样式变体测试（7）
+- [ ] 标题提示测试（6）
+- [ ] 交互扩展（4）
+- [ ] 边界测试（6）
+- [ ] 异常测试（4）
+- [ ] 可访问性测试（5）
+- [ ] Storybook 测试（10）
+
+#### Phase 3: 优化与完善 (P2) - 11 个用例
+- [ ] UI 布局细节（2）
+- [ ] 性能测试（5）
+- [ ] 边界测试扩展（3）
+- [ ] Storybook 自定义功能（1）
+
+---
+
+## 10. 测试覆盖率目标
+
+### 10.1 覆盖率指标
+
+| 指标 | 目标值 | 当前值 | 状态 |
+|------|--------|--------|------|
+| Statements | 80% | - | ⬜ |
+| Branches | 75% | - | ⬜ |
+| Functions | 80% | - | ⬜ |
+| Lines | 80% | - | ⬜ |
+
+---
+
+## 11. 测试用例编写规范
+
+### 11.1 命名规范
+
+```typescript
+// 测试文件命名
+Selector.test.tsx
+SelectorGroup.test.tsx
+useSelectionController.test.ts
+
+// 测试套件命名
+describe('Selector 组件', () => {
+  describe('单选模式', () => {
+    // 测试用例
+  });
+});
+
+// 测试用例命名
+test('应该正确渲染组件', () => {});
+test('应该在单选模式下使用 Radio', () => {});
+```
+
+### 11.2 测试用例结构
+
+```typescript
+describe('功能描述', () => {
+  // Arrange: 准备测试数据和环境
+  const defaultProps = { ... };
+  
+  // 清理函数（可选）
+  afterEach(() => {
+    cleanup();
+  });
+
+  test('具体测试场景', () => {
+    // Arrange: 准备
+    const handleChange = vi.fn();
+    
+    // Act: 执行
+    const { ... } = render(<Selector {...props} />);
+    // 执行操作...
+    
+    // Assert: 断言
+    expect(...).toBe(...);
+  });
+});
+```
+
+### 11.3 断言最佳实践
+
+```typescript
+// ✅ 好的实践
+expect(element).toBeInTheDocument();
+expect(element).toHaveTextContent('文本');
+expect(handleChange).toHaveBeenCalledWith(expectedValue);
+expect(handleChange).toHaveBeenCalledTimes(1);
+
+// ❌ 避免的实践
+expect(element).not.toBeNull(); // 使用 toBeInTheDocument()
+expect(getByText('文本')).toBeTruthy(); // 直接使用查询结果
+```
+
+### 11.4 异步测试处理
+
+```typescript
+// 使用 waitFor
+test('异步更新测试', async () => {
+  const { getByText } = render(<Selector />);
+  
+  await waitFor(() => {
+    expect(getByText('更新后的文本')).toBeInTheDocument();
+  });
+});
+
+// 使用 findBy
+test('异步查询测试', async () => {
+  const { findByText } = render(<Selector />);
+  const element = await findByText('异步文本');
+  expect(element).toBeInTheDocument();
+});
+```
+
+---
+
+## 12. Storybook 可视化测试
+
+### 12.1 Storybook 概述
+
+**Storybook** 是一个用于独立开发和测试 UI 组件的工具。它提供了一个隔离的环境来开发和测试组件，支持交互式组件预览、Props 调试、不同状态展示等。
+
+**在组件测试中的作用**：
+- ✅ **可视化验证**：直观查看组件在不同配置下的渲染效果
+- ✅ **交互测试**：手动测试组件的交互行为
+- ✅ **文档展示**：作为组件使用文档和示例
+- ✅ **回归测试**：通过视觉回归测试发现 UI 变化
+- ✅ **跨团队协作**：设计师和产品可以查看组件效果
+
+### 12.2 Storybook 环境配置
+
+#### 12.2.1 安装与启动
+
+```bash
+# 安装依赖（已在 package.json 中配置）
+pnpm install
+
+# 启动 Storybook
+cd packages/private-materials
+pnpm storybook
+
+# Storybook 将在 http://localhost:6006 启动
+```
+
+#### 12.2.2 配置文件
+
+**主要配置文件**：
+- `.storybook/main.js` - Storybook 主配置
+- `.storybook/preview.js` - Storybook 预览配置
+- `src/pro/Selector/Selector.stories.tsx` - Selector 组件的 Stories
+
+#### 12.2.3 依赖包
+
+```json
+{
+  "devDependencies": {
+    "@storybook/addon-essentials": "^7.6.19",
+    "@storybook/addon-interactions": "^7.6.19",
+    "@storybook/addon-links": "^7.6.19",
+    "@storybook/blocks": "^7.6.19",
+    "@storybook/react": "^7.6.19",
+    "@storybook/react-webpack5": "^7.6.19",
+    "storybook": "^7.6.19"
+  }
+}
+```
+
+### 12.3 Stories 测试用例
+
+#### 12.3.1 Stories 清单
+
+| Story 名称 | 测试场景 | 对应测试用例 | 优先级 |
+|-----------|---------|-------------|--------|
+| Default | 基础单选模式 | TC-S-001, TC-S-002 | P0 |
+| Multiple | 多选模式 | TC-M-001, TC-M-002 | P0 |
+| SingleWithQuantity | 单选 + 数量 | TC-Q-001, TC-Q-002 | P0 |
+| MultipleWithQuantity | 多选 + 数量 | TC-Q-001, TC-M-002 | P0 |
+| GridLayout2Columns | 2列网格布局 | TC-U-002 | P1 |
+| GridLayout3Columns | 3列网格布局 | TC-U-003 | P1 |
+| WithValidation | 校验规则 | TC-V-001 ~ TC-V-005 | P0 |
+| MutexGroups | 互斥组功能 | TC-V-004 | P0 |
+| Disabled | 禁用状态 | TC-I-003, TC-I-004 | P1 |
+| SelectVariant | Select 变体 | TC-SV-003 | P1 |
+| SelectVariantMultiple | 多选下拉 | TC-SV-003, TC-M-001 | P1 |
+| CardVariants | 卡片样式变体 | TC-SV-002, TC-SV-006, TC-SV-007 | P1 |
+| CustomIcon | 自定义图标 | - | P2 |
+| CustomRender | 自定义渲染 | - | P2 |
+| SelectorGroupBasic | 基础分组 | TC-G-001 | P1 |
+| SelectorGroupWithLinkage | 联动规则 | TC-G-002 | P1 |
+
+#### 12.3.2 Stories 使用示例
+
+**基础 Story 定义**：
+
+```typescript
+import type { Meta, StoryObj } from '@storybook/react';
+import Selector from './index';
+
+const meta: Meta<typeof Selector> = {
+  title: 'Pro Components/Selector',
+  component: Selector,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component: '高级选择器组件，支持单选/多选、数量控制、校验规则等功能。',
+      },
+    },
+  },
+  argTypes: {
+    mode: {
+      control: 'select',
+      options: ['single', 'multiple'],
+      description: '选择模式：单选或多选',
+    },
+    valueType: {
+      control: 'select',
+      options: ['primitive', 'object'],
+      description: '值类型：原始值或对象值',
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof Selector>;
+
+// 基础 Story 示例
+export const Default: Story = {
+  args: {
+    id: 'default-selector',
+    title: '基础单选',
+    dataSource: [
+      { id: 1, value: 1, label: '选项1', title: '选项1' },
+      { id: 2, value: 2, label: '选项2', title: '选项2' },
+    ],
+    mode: 'single',
+    valueType: 'primitive',
+    fieldNames: { value: 'value', label: 'label' },
+  },
+  render: (args) => {
+    const [value, setValue] = useState<SelectionValue>(1);
+    return (
+      <Selector
+        {...args}
+        value={value}
+        onChange={(v) => {
+          setValue(v);
+          console.log('选中值:', v);
+        }}
+      />
+    );
+  },
+};
+```
+
+### 12.4 Storybook 测试方法
+
+#### 12.4.1 可视化测试
+
+**测试步骤**：
+1. 启动 Storybook：`pnpm storybook`
+2. 在浏览器中打开 `http://localhost:6006`
+3. 选择对应的 Story
+4. 验证组件的视觉呈现是否符合预期
+
+**测试检查项**：
+- ✅ 组件正确渲染，无错误提示
+- ✅ 样式正确显示（布局、颜色、间距等）
+- ✅ 交互状态正确（悬停、选中、禁用等）
+- ✅ 响应式布局正确（不同屏幕尺寸）
+
+#### 12.4.2 交互测试
+
+**使用 Storybook 的交互面板**：
+
+1. **手动交互测试**：
+   - 点击选项，验证选中状态
+   - 调整数量，验证数量控制
+   - 切换不同模式，验证行为差异
+
+2. **Controls 面板测试**：
+   - 调整 `mode` 属性，观察组件变化
+   - 修改 `valueType`，验证值类型切换
+   - 切换 `variant`，查看不同样式变体
+
+3. **Actions 面板**：
+   - 观察 `onChange` 回调的输出
+   - 验证事件触发的参数是否正确
+
+#### 12.4.3 边界场景测试
+
+在 Storybook 中可以方便地测试各种边界场景：
+
+```typescript
+// 空数据源测试
+export const EmptyDataSource: Story = {
+  args: {
+    dataSource: [],
+    title: '空数据源',
+  },
+};
+
+// 单条数据测试
+export const SingleItem: Story = {
+  args: {
+    dataSource: [
+      { id: 1, value: 1, label: '唯一选项', title: '唯一选项' },
+    ],
+  },
+};
+
+// 大量数据测试（性能验证）
+export const LargeDataset: Story = {
+  args: {
+    dataSource: Array.from({ length: 100 }, (_, i) => ({
+      id: i + 1,
+      value: i + 1,
+      label: `选项${i + 1}`,
+      title: `选项${i + 1}`,
+    })),
+  },
+};
+```
+
+#### 12.4.4 跨浏览器测试
+
+使用 Storybook 在不同浏览器中测试：
+- Chrome
+- Firefox
+- Safari
+- Edge
+
+**测试重点**：
+- ✅ 样式兼容性
+- ✅ 交互行为一致性
+- ✅ 性能表现
+
+### 12.5 Storybook 与单元测试的区别
+
+| 对比项 | Storybook | 单元测试 (Vitest) |
+|-------|-----------|-------------------|
+| **测试类型** | 可视化、手动验证 | 自动化、断言验证 |
+| **执行方式** | 手动运行，人工检查 | 自动运行，CI/CD |
+| **测试场景** | UI 渲染、交互体验 | 逻辑正确性、边界条件 |
+| **覆盖范围** | 核心场景、典型用例 | 全面覆盖、边界异常 |
+| **反馈速度** | 即时可视化 | 快速执行结果 |
+| **维护成本** | 需要人工检查 | 自动化维护 |
+| **适用场景** | 开发调试、UI 验收 | 回归测试、CI 集成 |
+
+**互补关系**：
+- ✅ **Storybook**：用于开发阶段的快速验证和 UI 验收
+- ✅ **单元测试**：用于保证逻辑正确性和自动化回归测试
+- ✅ **两者结合**：Storybook 确保 UI 正确，单元测试确保逻辑正确
+
+### 12.6 Storybook 测试用例执行清单
+
+#### 12.6.1 基础功能验证
+
+- [ ] **Default**: 单选模式正常渲染
+- [ ] **Multiple**: 多选模式正常渲染
+- [ ] **SingleWithQuantity**: 单选 + 数量功能正常
+- [ ] **MultipleWithQuantity**: 多选 + 数量功能正常
+
+#### 12.6.2 布局验证
+
+- [ ] **GridLayout2Columns**: 2列布局正确
+- [ ] **GridLayout3Columns**: 3列布局正确
+- [ ] 响应式布局在不同屏幕尺寸下正常
+
+#### 12.6.3 校验功能验证
+
+- [ ] **WithValidation**: 校验规则生效
+- [ ] **MutexGroups**: 互斥组功能正确
+- [ ] 错误信息正确显示
+
+#### 12.6.4 样式变体验证
+
+- [ ] **SelectVariant**: Select 变体正常
+- [ ] **CardVariants**: 卡片样式变体正确
+- [ ] **CustomIcon**: 自定义图标正常显示
+- [ ] **CustomRender**: 自定义渲染正确
+
+#### 12.6.5 分组组件验证
+
+- [ ] **SelectorGroupBasic**: 基础分组功能
+- [ ] **SelectorGroupWithLinkage**: 联动规则生效
+
+### 12.7 Storybook 测试最佳实践
+
+#### 12.7.1 Story 组织原则
+
+```typescript
+// ✅ 好的实践：按功能分组
+export default {
+  title: 'Pro Components/Selector',
+  component: Selector,
+};
+
+// ✅ 好的实践：清晰的 Story 命名
+export const SingleSelection = { ... };
+export const MultipleSelection = { ... };
+export const WithQuantity = { ... };
+
+// ❌ 避免的实践：模糊的命名
+export const Test1 = { ... };
+export const Example = { ... };
+```
+
+#### 12.7.2 Story 参数配置
+
+```typescript
+// ✅ 好的实践：提供完整的 argTypes
+const meta: Meta<typeof Selector> = {
+  argTypes: {
+    mode: {
+      control: 'select',
+      options: ['single', 'multiple'],
+      description: '选择模式',
+      table: {
+        type: { summary: 'single | multiple' },
+        defaultValue: { summary: 'single' },
+      },
+    },
+  },
+};
+
+// ✅ 好的实践：使用真实数据
+export const RealWorldExample: Story = {
+  args: {
+    dataSource: realisticDataSource, // 使用真实业务数据
+  },
+};
+```
+
+#### 12.7.3 交互式测试
+
+```typescript
+// ✅ 好的实践：使用 Controls 进行交互测试
+export const InteractiveExample: Story = {
+  args: {
+    // 所有 props 都可以通过 Controls 面板调整
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: '使用 Controls 面板调整属性，实时查看组件变化。',
+      },
+    },
+  },
+};
+```
+---
+
+## 13. 测试维护指南
+
+### 13.1 测试用例更新
+
+当组件发生变更时：
+1. ✅ 检查现有测试用例是否需要更新
+2. ✅ 添加新功能的测试用例
+3. ✅ 更新测试数据以覆盖新场景
+4. ✅ 确保所有测试通过
+
+### 13.2 测试用例审查清单
+
+- [ ] 测试用例覆盖核心功能
+- [ ] 边界条件有测试覆盖
+- [ ] 异常情况有处理
+- [ ] 测试代码可读性强
+- [ ] 测试数据合理
+- [ ] 断言准确明确
+- [ ] 无冗余测试
+
+---
+
+## 14. 附录
+
+### 14.1 测试工具参考
+
+- [Vitest 文档](https://vitest.dev/)
+- [React Testing Library 文档](https://testing-library.com/react)
+- [Testing Library 查询优先级](https://testing-library.com/docs/queries/about/#priority)
+- [Storybook 文档](https://storybook.js.org/)
+- [Storybook React 文档](https://storybook.js.org/docs/react/get-started/introduction)
+
+### 14.2 相关文档
+
+- [开发文档](https://studio.picoding-dev.com/pro-components/selector?tab=dev)
+- [设计文档](https://m1ed09stz4r.feishu.cn/wiki/NL5AwOs0ei5ZBekT4i6cuzIOnoM)
+- [Storybook 使用指南](./STORYBOOK.md)