stepsCompleted: ['step-01-validate-prerequisites', 'step-02-design-epics', 'step-03-create-stories'] inputDocuments:

name: PRD - E2E测试工具包 path: _bmad-output/planning-artifacts/prd.md type: prd
name: Architecture - E2E测试工具包 path: _bmad-output/planning-artifacts/architecture.md type: architecture
name: E2E Radix UI 测试标准 path: docs/standards/e2e-radix-testing.md type: testing-standard ---

188-179-template-6 - Epic Breakdown

Overview

This document provides the complete epic and story breakdown for 188-179-template-6，从残疾人管理 E2E 测试实践中提取可复用的测试工具包。

Requirements Inventory

Functional Requirements

Radix UI Select 组件测试支持 (FR1-FR6):

FR1: 测试开发者可以使用工具函数选择静态枚举型 Radix UI Select 下拉框的选项
FR2: 测试开发者可以使用工具函数选择异步加载型 Radix UI Select 下拉框的选项
FR3: 工具函数可以自动处理 Radix UI Select 的 DOM 结构和交互流程
FR4: 工具函数可以等待异步加载的选项出现在下拉列表中
FR5: 工具函数可以提供清晰的错误提示，包含标签、期望值等上下文信息
FR6: 工具函数可以区分"元素未找到"和"超时"错误类型

文件上传测试支持 (FR7-FR10):

FR7: 测试开发者可以使用工具函数上传文件到指定的文件输入字段
FR8: 工具函数可以从 fixtures 目录加载测试文件
FR9: 工具函数可以支持多文件上传场景
FR10: 工具函数可以验证文件上传是否成功完成

表单交互测试支持 (FR11-FR15):

FR11: 测试开发者可以使用工具函数填写多步骤表单
FR12: 工具函数可以滚动页面到特定的表单区域
FR13: 工具函数可以处理表单验证错误场景
FR14: 测试开发者可以使用工具函数提交表单并等待响应
FR15: 工具函数可以支持常见的表单字段类型（文本、选择器、日期等）

动态列表测试支持 (FR16-FR20):

FR16: 测试开发者可以使用工具函数向动态列表中添加新项
FR17: 测试开发者可以使用工具函数从动态列表中删除项
FR18: 工具函数可以支持不同类型的动态列表项（银行卡、备注等）
FR19: 工具函数可以验证动态列表项添加或删除后的状态
FR20: 工具函数可以处理动态列表的异步更新场景

对话框操作测试支持 (FR21-FR24):

FR21: 测试开发者可以使用工具函数统一操作对话框（确认、取消、关闭）
FR22: 工具函数可以等待对话框完全关闭后再继续执行
FR23: 工具函数可以处理对话框内的表单填写和提交
FR24: 工具函数可以验证对话框是否按预期打开或关闭

测试工具包基础设施 (FR25-FR32):

FR25: 测试开发者可以通过 npm workspace 协议安装测试工具包
FR26: 工具包可以作为 peer dependency 依赖 Playwright，不增加运行时依赖
FR27: 工具包提供完整的 TypeScript 类型定义和类型提示
FR28: 工具包的所有导出函数都有完整的 JSDoc 注释
FR29: 工具包使用严格类型检查，不使用 any 类型
FR30: 工具包支持目标 ES2020+ 的 JavaScript 环境
FR31: 工具包的每个工具函数都可以独立导入和使用
FR32: 工具包可以与其他测试工具和库兼容使用

文档和开发者支持 (FR33-FR40):

FR33: 测试开发者可以通过 README 快速了解工具包的用途和安装方法
FR34: 文档提供每个工具函数的详细使用示例
FR35: 文档提供静态 Select 和异步 Select 的区别说明
FR36: 文档提供从现有测试代码迁移到工具函数的指南
FR37: 文档提供常见问题和解决方案
FR38: 文档提供残疾人管理测试作为完整的使用示例
FR39: 测试开发者可以在 30 分钟内使用工具函数编写第一个测试
FR40: 工具包的使用示例覆盖所有 6 个核心工具函数

测试质量和稳定性保障 (FR41-FR45):

FR41: 工具函数使用 Playwright 的 auto-waiting 机制防止时序问题
FR42: 工具函数为静态选项设置合理的默认超时配置
FR43: 工具函数为异步选项提供可配置的超时参数
FR44: 工具函数可以支持重试机制处理不稳定的网络请求
FR45: 工具函数可以在测试连续运行 20 次时保持 100% 通过率

可扩展性和维护性 (FR46-FR50):

FR46: 工具函数支持配置对象参数，允许自定义行为
FR47: 工具函数设计支持未来的 Radix UI 版本升级
FR48: 工具函数使用稳定的选择器策略（role、data-testid）
FR49: 工具包预留扩展接口，支持新增其他 Radix 组件测试模式
FR50: 工具包的代码结构清晰，便于团队贡献和维护

NonFunctional Requirements

可靠性 (NFR1-NFR7):

NFR1: 工具函数在相同条件下连续运行 20 次，必须保持 100% 通过率，无 flaky 失败
NFR2: 工具函数能够正确处理异步加载场景，避免时序问题导致的测试失败
NFR3: 当 DOM 元素暂时不可用时，工具函数提供清晰的错误消息，而不是超时无响应
NFR4: 工具函数能够区分产品 bug 和测试代码问题，帮助开发者快速定位问题根源
NFR5: 当选择操作失败时，错误消息包含：下拉框标签名称、期望选择的值、实际可用的选项列表、失败原因
NFR6: 当文件上传失败时，错误消息包含文件路径、选择器、失败原因
NFR7: 错误消息格式统一，便于日志分析和问题定位

性能 (NFR8-NFR14):

NFR8: 单个 Radix UI Select 选择操作（静态）应在 2 秒内完成
NFR9: 单个 Radix UI Select 选择操作（异步）应在 5 秒内完成（默认超时）
NFR10: 工具函数本身的开销不超过 100ms（不包括 Playwright 操作时间）
NFR11: 使用工具函数的测试比手动编写 DOM 操作的测试执行时间差异 < 10%
NFR12: 静态选项使用合理的默认超时（2 秒），避免不必要的等待
NFR13: 异步选项提供可配置的超时参数，默认值为 5 秒
NFR14: 工具函数使用 Playwright 的 auto-waiting 机制，减少显式等待的需要

集成性 (NFR15-NFR24):

NFR15: 工具包兼容 Playwright 最新稳定版本和上一个 LTS 版本
NFR16: 工具包可以作为 peer dependency 引用，不增加运行时依赖
NFR17: 工具函数接受标准 Playwright Page 对象作为参数
NFR18: 工具包不依赖特定版本的 Playwright，使用灵活的版本范围
NFR19: 工具函数可以在任何使用 Playwright 的测试框架中运行（Vitest、Jest 等）
NFR20: 工具包不修改全局配置，不需要额外的测试框架配置
NFR21: 工具函数可以与现有的 Page Object 模式无缝集成
NFR22: 工具包通过 pnpm workspace 协议安装，支持本地开发
NFR23: 工具包的构建产物与项目的 TypeScript 配置兼容
NFR24: 工具包的类型定义可以自动被 IDE 识别和提示

代码质量 (NFR25-NFR40):

NFR25: 工具包使用 TypeScript 严格模式，无 any 类型
NFR26: 所有导出函数都有完整的参数类型和返回值类型
NFR27: 类型定义支持 IDE 自动补全和类型检查
NFR28: 类型错误在编译时被捕获，不在运行时暴露
NFR29: 工具包的代码覆盖率 ≥ 80%
NFR30: 每个工具函数都有对应的单元测试
NFR31: 代码遵循项目的 ESLint 和 Prettier 配置
NFR32: 函数复杂度保持在低水平（圈复杂度 < 10）
NFR33: 每个导出函数都有完整的 JSDoc 注释
NFR34: README 包含快速入门、安装说明、基本用法
NFR35: 每个工具函数至少有 1 个实际使用示例
NFR36: 文档说明静态 Select 和异步 Select 的区别和使用场景
NFR37: 新测试开发者可以在 30 分钟内使用工具函数编写第一个测试
NFR38: 工具函数的命名清晰直观，不需要频繁查看文档
NFR39: 函数参数设计简洁，必需参数 ≤ 3 个
NFR40: 错误消息对新手友好，包含问题诊断和建议修复步骤

兼容性 (NFR41-NFR46):

NFR41: 工具函数在 Playwright 支持的所有浏览器中正常工作（Chromium、Firefox、WebKit）
NFR42: 工具函数在 headless 和 headed 模式下都能正常工作
NFR43: 工具函数在 CI/CD 环境中稳定运行
NFR44: 工具包支持 Node.js 当前 LTS 版本和上一个 LTS 版本
NFR45: 工具包的设计考虑未来 Radix UI 版本升级，使用稳定的选择器策略
NFR46: 重大版本变更时提供迁移指南

Additional Requirements

从 Architecture 文档提取的技术需求:

包结构需求:

创建独立包 packages/e2e-test-utils，与现有的 @d8d/shared-test-util（后端集成测试）分离
按功能分组文件结构：src/ 分为 radix-select.ts, file-upload.ts, form-helper.ts, dialog.ts, dynamic-list.ts
共享代码集中在 types.ts, errors.ts, constants.ts
主导出使用 index.ts，支持 tree-shaking

API 设计需求:

必需参数 ≤ 3 个，复杂配置通过可选对象传递
函数命名：动词+名词，camelCase（如 selectRadixOption）
异步函数添加 Async 后缀（如 selectRadixOptionAsync）
类型命名：接口 PascalCase + Options 后缀（如 AsyncSelectOptions）

类型系统需求:

分层类型：types.ts 存放共享类型（BaseOptions），各模块文件存放特定类型
所有配置对象继承 BaseOptions
TypeScript 严格模式，无 any 类型

选择器策略需求:

混合策略优先级：data-testid → aria-label + role → text content + role
推荐在 Radix 组件上添加 data-testid

错误处理需求:

使用结构化错误类 E2ETestError + ErrorContext
错误消息格式：❌ 操作失败、上下文信息、💡 修复建议

测试策略需求:

三层测试：单元测试（Vitest）、集成测试（Playwright）、稳定性测试（20次连续运行）
创建独立测试应用 tests/test-app/ 使用 Vite + React
测试应用提供真实的 @d8d/shared-ui-components 组件
Playwright 配置自动启动测试应用服务器
单元测试覆盖率 ≥ 80%

常量定义需求:

超时常量：DEFAULT_TIMEOUTS.static = 2000, async = 5000, networkIdle = 10000
选择器策略常量：SELECTOR_STRATEGIES 数组

文档需求:

完整的 JSDoc 注释格式
README 包含快速入门、安装说明、基本用法
每个工具函数至少有 1 个实际使用示例
迁移指南：从现有测试代码迁移到工具函数

遵循项目标准:

遵循 docs/standards/testing-standards.md 中的测试规范
遵循 docs/standards/web-ui-testing-standards.md 中的 Web UI 测试规范
遵循 docs/standards/e2e-radix-testing.md 中的 Radix UI E2E 测试标准（核心标准文档）

从 E2E Radix UI 测试标准提取的详细需求:

核心工具函数签名（必须按此实现）:

// Radix UI Select 工具
selectRadixOption(page: Page, label: string, value: string): Promise<void>
selectRadixOptionAsync(page: Page, label: string, value: string, options?: AsyncSelectOptions): Promise<void>

// 文件上传工具
uploadFileToField(page: Page, selector: string, fileName: string): Promise<void>

// 表单辅助工具
fillMultiStepForm(page: Page, steps: FormStep[]): Promise<void>
scrollToSection(page: Page, sectionName: string): Promise<void>

// 动态列表工具
addDynamicListItem(page: Page, itemType: string, data: Record<string, any>): Promise<void>
deleteDynamicListItem(page: Page, itemType: string, index: number): Promise<void>

// 对话框工具
handleDialog(page: Page, action: 'confirm' | 'cancel' | 'close'): Promise<void>
waitForDialogClosed(page: Page): Promise<void>
cancelDialog(page: Page): Promise<void>

DOM 结构理解需求:

理解 Radix UI Select 的典型 DOM 结构：data-radix-select-trigger 触发器，role="listbox" 选项列表，role="option" 单个选项
理解 Radix UI Dialog 的 DOM 结构：role="dialog" 对话框容器
理解数据属性：data-value 用于选项值，data-state 用于状态跟踪

选择器策略实现细节:

// 触发器选择器优先级
const TRIGGER_SELECTORS = [
  `[data-testid="${label}-trigger"]`,  // 最高优先级
  `text="${label}"`,                     // 文本匹配
  `[role="combobox"]`                    // 兜底
];

// 选项选择器优先级
const OPTION_SELECTORS = [
  `[role="option"][data-value="${value}"]`,  // data-testid + data-value
  `[role="option"]:has-text("${value}")`      // 文本匹配兜底
];

性能标准（来自测试标准文档）: | 操作 | 目标时间 | 最大可接受时间 | |------|---------|---------------| | 静态 Select 选择 | < 1s | 2s | | 异步 Select 选择 | < 3s | 5s | | 文件上传 | < 2s | 5s | | 表单提交 | < 2s | 5s |

Fixtures 目录结构标准:

web/tests/
└── fixtures/
    ├── images/        # 测试图片（身份证照片、残疾证照片等）
    └── documents/     # 测试文档（PDF 等）

错误消息格式标准:

Error: Radix Select 选项 "xxx" 未找到
  标签: 残疾类型
  期望值: xxx
  可用选项: 视力残疾, 听力残疾, 肢体残疾, 智力残疾

Error: Radix Select 等待超时
  标签: 省份
  期望值: 广东省
  超时时间: 5000ms
  可能原因: 网络请求过慢或选项未加载

测试稳定性最佳实践:

使用 Playwright 的 auto-waiting 机制，不使用 waitForTimeout
优先使用 data-testid 选择器，谨慎使用文本选择器，避免使用不稳定的 CSS 类
测试隔离：每个测试前清理数据，失败时截图
明确的错误断言：使用具体的选择器和期望的文本内容

完整示例需求:

提供残疾人管理 E2E 测试作为完整示例
演示静态 Select、异步 Select、文件上传、动态列表、对话框的综合使用
展示与 Page Object 模式的集成方式

FR Coverage Map

FR 范围	Epic	描述
FR1-FR6	Epic 1	Radix UI Select 测试支持（静态和异步）
FR25-FR32	Epic 1	包基础设施（package.json、类型定义、配置）
FR7-FR24, FR46-FR50	Epic 3	扩展工具集（文件上传、表单、列表、对话框、可扩展性）
FR41-FR45	Epic 2 & 4	质量与稳定性（Select 验证、全面验证、稳定性测试）
FR33-FR40	Epic 5	文档与开发者体验（README、示例、迁移指南）

Epic 规划变更说明（2026-01-09）：

Epic 1: ✅ 已完成（Select 工具基础框架）
Epic 2: 🆕 新增（在现有 E2E 测试中验证 Select 工具）
Epic 3: 原 Epic 2（扩展工具集）
Epic 4: 原 Epic 3（全面验证工具包）
Epic 5: 原 Epic 4（完善文档与开发者体验）

Epic List

Epic 1: 测试工具包基础框架与 Select 支持

目标： 测试开发者可以安装 @d8d/e2e-test-utils 包，立即使用 Select 工具测试 Radix UI Select 组件（最常用、最关键的测试场景）。

交付物：

完整的包结构和配置（package.json, tsconfig.json, vitest.config.ts）
selectRadixOption() 和 selectRadixOptionAsync() 函数
类型定义和错误处理（E2ETestError, ErrorContext）
选择器策略实现（testid → ARIA → text）
基础文档（README 安装、快速入门）
单元测试（Vitest）

FRs covered: FR1-FR6, FR25-FR32

用户价值：

可以安装并立即使用 Select 工具
无需深入了解 Radix UI DOM 结构
自动处理时序问题
清晰的错误提示

Epic 2: 扩展工具集（文件上传、表单、列表、对话框）

目标： 测试开发者可以使用完整的 6 个核心工具函数，覆盖所有常见 E2E 测试场景。

交付物：

uploadFileToField() - 文件上传工具
fillMultiStepForm(), scrollToSection() - 表单辅助工具
addDynamicListItem(), deleteDynamicListItem() - 动态列表工具
handleDialog(), waitForDialogClosed(), cancelDialog() - 对话框工具
Fixtures 目录结构示例
单元测试

FRs covered: FR7-FR24, FR46-FR50

用户价值：

完整的工具集覆盖所有常见测试场景
统一的 API 设计和错误处理
支持可配置和扩展

Epic 3: 在残疾人管理中验证工具包

目标： 工具包在真实的残疾人管理 E2E 测试中验证，证明工具函数可用且稳定，提供完整的参考示例。

交付物：

残疾人管理 E2E 测试（使用工具函数）
照片上传功能测试
银行卡管理功能测试
备注功能测试
回访功能测试
完整流程测试
稳定性验证（20次连续运行 100% 通过）

FRs covered: FR38, FR41-FR45

用户价值：

验证工具包的可用性和稳定性
提供完整的参考示例
证明工具包符合性能标准

Epic 4: 完善文档与开发者体验

目标： 测试开发者可以在 30 分钟内上手使用工具包，有完整的文档、示例和迁移指南。

交付物：

完整的 README（安装、快速入门、API 文档）
每个工具函数的详细使用示例
迁移指南（从现有测试代码到工具函数）
常见问题和解决方案
残疾人管理测试作为完整示例
JSDoc 完整注释

FRs covered: FR33-FR40

用户价值：

快速上手（30 分钟内编写第一个测试）
清晰的文档和示例
降低学习曲线
便于团队采用

Epic 1: 测试工具包基础框架与 Select 支持

目标： 测试开发者可以安装 @d8d/e2e-test-utils 包，立即使用 Select 工具测试 Radix UI Select 组件（最常用、最关键的测试场景）。

Story 1.1: 创建包基础结构和配置

作为测试开发者，我想要可以安装 @d8d/e2e-test-utils 包，以便在项目中使用测试工具函数。

验收标准：

Given 项目是 Monorepo 结构 When 创建 packages/e2e-test-utils/ 目录 Then 目录结构包含 src/, tests/, package.json, tsconfig.json, vitest.config.ts And package.json 包含正确的包名、版本、peer dependencies（@playwright/test） And tsconfig.json 启用严格模式，目标 ES2020+ And 可以通过 pnpm add -D @d8d/e2e-test-utils@workspace:* 安装

Story 1.2: 实现类型定义和错误处理

作为测试开发者，我想要工具包有完整的类型支持和统一的错误处理，以便获得类型安全和清晰的错误提示。

验收标准：

Given 包结构已创建 When 实现 src/types.ts, src/errors.ts, src/constants.ts Then types.ts 导出 BaseOptions, AsyncSelectOptions, FileUploadOptions 等 And errors.ts 导出 E2ETestError 类和 ErrorContext 接口 And constants.ts 定义 DEFAULT_TIMEOUTS（static: 2000, async: 5000） And 所有类型使用 TypeScript 严格模式，无 any 类型

Story 1.3: 实现静态 Select 工具函数

作为测试开发者，我想要使用 selectRadixOption() 函数选择静态枚举型下拉框，以便无需理解 Radix UI DOM 结构就能编写测试。

验收标准：

Given 类型定义已创建 When 实现 src/radix-select.ts 中的 selectRadixOption() 函数 Then 函数签名：selectRadixOption(page: Page, label: string, value: string): Promise<void> And 选择器策略：data-testid → aria-label + role → text content And 自动处理点击触发器、等待选项列表、点击选项 And 错误时抛出 E2ETestError，包含标签、期望值、可用选项 And 操作在 2 秒内完成（NFR8）

Story 1.4: 实现异步 Select 工具函数

作为测试开发者，我想要使用 selectRadixOptionAsync() 函数选择异步加载的下拉框，以便测试省份、城市等动态加载的选项。

验收标准：

Given 静态 Select 函数已实现 When 实现 selectRadixOptionAsync(page, label, value, options?) 函数 Then 支持 AsyncSelectOptions 配置（timeout, waitForOption） And 使用 waitForLoadState('networkidle') 等待异步加载 And 默认超时 5 秒，可配置 And 超时时提供清晰错误消息（标签、期望值、超时时间、可能原因）

Story 1.5: 创建主导出和基础文档

作为测试开发者，我想要可以导入工具函数并查看快速入门文档，以便快速开始使用工具包。

验收标准：

Given Select 工具函数已实现 When 创建 src/index.ts 和 README.md Then index.ts 导出所有公共函数和类型（tree-shakeable） And README 包含：安装说明、快速入门、Select 使用示例 And 所有导出函数有完整的 JSDoc 注释 And 可以 import { selectRadixOption } from '@d8d/e2e-test-utils'

Story 1.6: Select 工具函数单元测试

作为测试开发者，我想要 Select 工具函数有充分的单元测试，以便确保函数的正确性和稳定性。

验收标准：

Given Select 工具函数已实现 When 创建 tests/unit/radix-select.test.ts Then 测试覆盖率 ≥ 80%（NFR29） And 测试用例包括：成功选择、选项不存在、超时、错误处理 And 使用 Vitest 运行测试 And 所有测试通过

Epic 2: 在现有 E2E 测试中验证 Select 工具

目标： 在 web/tests/e2e/ 的现有残疾人管理测试中使用 Select 工具，验证工具在真实场景中的可用性和稳定性，收集实际使用反馈，为后续工具设计提供指导。

背景： Epic 1 已完成 Select 工具的开发和单元测试，但尚未在真实 E2E 测试场景中验证。通过在现有测试中使用这些工具，我们可以：

验证工具在实际业务场景中的可用性
发现并修复潜在问题
收集使用体验反馈，改进 API 设计
为后续工具开发建立信心和经验

范围：

✅ 使用现有 web/tests/e2e/ 测试基础设施
✅ 使用现有的残疾人管理测试场景
✅ 替换 Page Object 中现有的 Select 操作
❌ 不创建新的测试应用
❌ 不添加新功能（仅验证现有功能）

依赖：

Epic 1: ✅ 已完成（Select 工具已开发）

验收标准：

Select 工具在至少 2 个真实 E2E 测试场景中使用
所有测试连续运行 10 次，100% 通过率
发现的问题已记录并修复（或列入待办）
收集的使用反馈已整理

Story 2.1: 在 web 目录安装 @d8d/e2e-test-utils

作为测试开发者，我想要在 web 目录安装 @d8d/e2e-test-utils 包，以便在 E2E 测试中使用 Select 工具。

验收标准：

Given Epic 1 已完成，@d8d/e2e-test-utils 包已构建 When 在 web/package.json 中添加 workspace 依赖 Then 可以在 web/tests/e2e/ 中导入 Select 工具 And TypeScript 类型检查通过 And 运行时无依赖错误

实现要点：

使用 pnpm add -D @d8d/e2e-test-utils@workspace:* 安装
验证 web/tests/e2e/ 中可以导入：import { selectRadixOption } from '@d8d/e2e-test-utils'

Story 2.2: 使用 selectRadixOption 重写残疾类型选择

作为测试开发者，我想要使用 selectRadixOption() 替换 Page Object 中的 Select 操作，以便验证工具在静态 Select 场景中的可用性。

验收标准：

Given @d8d/e2e-test-utils 已安装 When 修改 web/tests/e2e/pages/admin/disability-person.page.ts Then fillBasicForm() 中的残疾类型选择使用 selectRadixOption() And fillBasicForm() 中的残疾等级选择使用 selectRadixOption() And 移除原有的 selectRadixOption() 方法 And 测试通过，功能正常

验证场景：

残疾类型：视力残疾、听力残疾、肢体残疾、言语残疾等（静态选项）
残疾等级：一级、二级、三级、四级（静态选项）

Story 2.3: 使用 selectRadixOptionAsync 重写省份/城市选择

作为测试开发者，我想要使用 selectRadixOptionAsync() 处理异步加载的 Select，以便验证工具在异步 Select 场景中的可用性。

验收标准：

Given @d8d/e2e-test-utils 已安装 When 修改 web/tests/e2e/pages/admin/disability-person.page.ts Then fillBasicForm() 中的省份选择使用 selectRadixOptionAsync() And fillBasicForm() 中的城市选择使用 selectRadixOptionAsync() And 移除 waitForTimeout(500) 等待城市加载的 hack And 测试通过，功能正常

验证场景：

省份选择（异步加载选项）
城市选择（根据省份动态加载）

配置要点：

使用 waitForOption: true 等待选项加载
使用合理的超时配置（5-10 秒）

Story 2.4: 运行测试并收集问题和改进建议

作为测试开发者，我想要运行使用新工具的测试并收集反馈，以便发现潜在问题并改进工具。

验收标准：

运行 web/tests/e2e/specs/admin/disability-person-complete.spec.ts
记录所有问题（包括失败的测试、错误消息、使用体验）
分类问题：工具 bug vs 使用错误 vs 改进建议
整理成问题清单

关注点：

工具是否按预期工作？
错误消息是否清晰？
API 是否简洁易用？
是否有性能问题？

Story 2.5: 修复发现的问题

作为测试开发者，我想要修复 Story 2.4 中发现的问题，以便工具可以正常使用。

验收标准：

所有标记为"工具 bug"的问题已修复
所有测试通过
修复已记录到 story 文件

优先级：

HIGH: 影响测试结果的问题（如选择失败、超时）
MEDIUM: 影响开发体验的问题（如错误消息不清晰）
LOW: 优化建议（如性能改进）

Story 2.6: 稳定性验证

作为测试开发者，我想要验证测试的稳定性，以便确保工具可以可靠地使用。

验收标准：

Given 所有问题已修复 When 连续运行测试 10 次 Then 所有测试 100% 通过 And 无 flaky 失败 And 平均执行时间 < 5 分钟

测试场景：

pnpm test:e2e:chromium disability-person-complete.spec.ts 运行 10 次

成功标准：

10/10 次通过 = 100% 稳定性 ✅
9/10 次通过 = 90% 稳定性，需要分析失败原因 ⚠️
< 9/10 次通过 = 稳定性不足，需要修复 ❌

Epic 3: 扩展工具集（文件上传、表单、列表、对话框）

目标： 测试开发者可以使用完整的 6 个核心工具函数，覆盖所有常见 E2E 测试场景。

说明： 本 Epic 原 Epic 2，已在 Epic 2 完成后重新编号。

Story 3.1: 实现文件上传工具

作为测试开发者，我想要使用 uploadFileToField() 函数上传文件，以便测试照片上传、文档上传等功能。

验收标准：

Given Epic 1 的类型定义已存在 When 实现 src/file-upload.ts 中的 uploadFileToField(page, selector, fileName) 函数 Then 函数从 fixtures 目录加载测试文件 And 使用 Playwright 的 setInputFiles() API And 支持相对路径（相对于 fixtures 目录） And 错误时提供清晰消息（文件路径、选择器、失败原因） And 操作在 5 秒内完成（NFR9）

Story 3.2: 实现表单辅助工具

作为测试开发者，我想要使用 fillMultiStepForm() 和 scrollToSection() 函数，以便测试多步骤表单和滚动操作。

验收标准：

Given 类型定义已存在 When 实现 src/form-helper.ts 中的表单辅助函数 Then fillMultiStepForm(page, steps) 支持分步填写表单 And scrollToSection(page, sectionName) 滚动到特定区域 And 支持常见字段类型（文本、选择器、日期等） And 自动处理表单验证错误场景

Story 3.3: 实现动态列表工具

作为测试开发者，我想要使用 addDynamicListItem() 和 deleteDynamicListItem() 函数，以便测试银行卡管理、备注管理等动态列表功能。

验收标准：

Given 类型定义已存在 When 实现 src/dynamic-list.ts 中的动态列表函数 Then addDynamicListItem(page, itemType, data) 添加新列表项 And deleteDynamicListItem(page, itemType, index) 删除指定索引的项 And 支持不同类型列表项（银行卡、备注等） And 验证列表状态变化 And 处理异步更新场景

Story 3.4: 实现对话框操作工具

作为测试开发者，我想要使用 handleDialog(), waitForDialogClosed(), cancelDialog() 函数，以便统一操作 Radix UI Dialog。

验收标准：

Given 类型定义已存在 When 实现 src/dialog.ts 中的对话框操作函数 Then handleDialog(page, action) 支持 confirm/cancel/close 操作 And waitForDialogClosed(page) 等待对话框完全关闭 And cancelDialog(page) 提供取消操作的快捷方式 And 理解 Radix UI Dialog 的 DOM 结构（role="dialog"） And 等待对话框关闭后再继续后续操作

Story 3.5: 更新主导出和 Fixtures 示例

作为测试开发者，我想要可以导入所有新增的工具函数，并参考 Fixtures 目录结构示例。

验收标准：

Given 所有扩展工具函数已实现 When 更新 src/index.ts 和创建 Fixtures 目录示例 Then index.ts 导出所有新函数（uploadFileToField, fillMultiStepForm 等） And 创建 tests/fixtures/ 目录结构示例 And Fixtures 包含 images/ 和 documents/ 子目录 And 提供示例测试文件（sample-id-card.jpg 等） And 所有函数有完整的 JSDoc 注释

Story 3.6: 扩展工具集单元测试

作为测试开发者，我想要所有扩展工具函数有充分的单元测试，以便确保函数的正确性和稳定性。

验收标准：

Given 扩展工具函数已实现 When 创建 tests/unit/ 下的测试文件 Then 测试覆盖率 ≥ 80%（NFR29） And 测试文件包括：file-upload.test.ts, form-helper.test.ts, dynamic-list.test.ts, dialog.test.ts And 每个函数的成功和失败场景都有测试 And 使用 Vitest 运行，所有测试通过

Epic 4: 在残疾人管理中验证工具包

目标： 工具包在真实的残疾人管理 E2E 测试中验证，证明工具函数可用且稳定，提供完整的参考示例。

说明： 本 Epic 原 Epic 3，已在 Epic 2 完成后重新编号。

注意： 原 Epic 3 的范围需要调整，因为 Epic 2 已涵盖 Select 工具的验证。

Story 4.2: 照片上传功能测试（使用现有测试）

作为测试开发者，我想要在现有的残疾人管理 E2E 测试中使用文件上传工具，以便验证 uploadFileToField() 的可用性。

验收标准：

Given Epic 3 已完成，文件上传工具已实现 When 在 web/tests/e2e/specs/admin/disability-person-complete.spec.ts 中使用 uploadFileToField() Then 上传身份证照片（正面、反面） And 上传残疾证照片 And 验证文件上传成功 And 测试使用 web/tests/e2e/fixtures/images/ 中的示例文件

Story 4.3: 银行卡管理功能测试（使用现有测试）

作为测试开发者，我想要在现有的残疾人管理 E2E 测试中使用动态列表和对话框工具，以便验证这些工具的可用性。

验收标准：

Given Epic 3 已完成，对话框和动态列表工具已实现 When 在现有测试中使用 handleDialog(), addDynamicListItem(), deleteDynamicListItem() Then 打开添加银行卡对话框 And 填写银行卡信息（银行名称、卡号、持卡人） And 添加银行卡到列表 And 验证列表状态变化

Story 4.4: 备注和回访功能测试（使用现有测试）

作为测试开发者，我想要在现有的残疾人管理 E2E 测试中使用表单辅助工具，以便验证表单工具的综合使用。

验收标准：

Given Epic 3 已完成，表单辅助工具已实现 When 在现有测试中使用 fillMultiStepForm(), scrollToSection() Then 填写备注表单 And 滚动到回访区域 And 添加备注到列表 And 验证表单提交和列表更新

Story 4.5: 完整流程验证

作为测试开发者，我想要在现有的完整流程测试中使用所有工具，以便演示所有工具函数的综合使用。

验收标准：

Given Epic 2-4 的所有工具已在部分测试中验证 When 确保 disability-person-complete.spec.ts 使用所有工具 Then 基本信息：使用 selectRadixOption 和 selectRadixOptionAsync And 照片上传：使用 uploadFileToField And 银行卡管理：使用 handleDialog, addDynamicListItem, deleteDynamicListItem And 备注添加：使用 fillMultiStepForm, scrollToSection, addDynamicListItem And 所有测试通过

Story 4.6: 稳定性测试（使用现有测试）

作为测试开发者，我想要有稳定性测试验证工具包的可靠性，以便确保工具函数连续运行 20 次 100% 通过。

验收标准：

Given 完整流程测试已编写 When 创建 tests/stability/repeat-run.spec.ts Then 测试连续运行 20 次完整流程 And 验证 100% 通过率（NFR1） And 测试执行时间符合性能标准（NFR8-NFR11） And 无 flaky 失败 And 使用 Playwright 运行稳定性测试

Epic 5: 完善文档与开发者体验

目标： 测试开发者可以在 30 分钟内上手使用工具包，有完整的文档、示例和迁移指南。

说明： 本 Epic 原 Epic 4，已在 Epic 2 完成后重新编号。

Story 5.1: 完善 README、API 文档和示例

作为测试开发者，我想要有完整的 README 和 API 文档，以便快速上手使用工具包。

验收标准：

Given Epic 1-4 的所有功能已实现 When 完善 README.md 和 API 文档 Then README 包含：项目简介、安装说明、快速入门、API 文档 And 每个工具函数都有完整的使用示例 And 说明静态 Select 和异步 Select 的区别和使用场景 And 包含迁移指南（从现有测试代码到工具函数） And 包含常见问题和解决方案 And 残疾人管理测试作为完整示例 And 所有函数有完整的 JSDoc 注释

epics.md 34 KB Geçmiş Ham

188-179-template-6 - Epic Breakdown

Overview

Requirements Inventory

Functional Requirements

NonFunctional Requirements

Additional Requirements

FR Coverage Map

Epic List

Epic 1: 测试工具包基础框架与 Select 支持

Epic 2: 扩展工具集（文件上传、表单、列表、对话框）

Epic 3: 在残疾人管理中验证工具包

Epic 4: 完善文档与开发者体验

Epic 1: 测试工具包基础框架与 Select 支持

Story 1.1: 创建包基础结构和配置

Story 1.2: 实现类型定义和错误处理

Story 1.3: 实现静态 Select 工具函数

Story 1.4: 实现异步 Select 工具函数

Story 1.5: 创建主导出和基础文档

Story 1.6: Select 工具函数单元测试

Epic 2: 在现有 E2E 测试中验证 Select 工具

Story 2.1: 在 web 目录安装 @d8d/e2e-test-utils

Story 2.2: 使用 selectRadixOption 重写残疾类型选择

Story 2.3: 使用 selectRadixOptionAsync 重写省份/城市选择

Story 2.4: 运行测试并收集问题和改进建议

Story 2.5: 修复发现的问题

Story 2.6: 稳定性验证

Epic 3: 扩展工具集（文件上传、表单、列表、对话框）

Story 3.1: 实现文件上传工具

Story 3.2: 实现表单辅助工具

Story 3.3: 实现动态列表工具

Story 3.4: 实现对话框操作工具

Story 3.5: 更新主导出和 Fixtures 示例

Story 3.6: 扩展工具集单元测试

Epic 4: 在残疾人管理中验证工具包

Story 4.2: 照片上传功能测试（使用现有测试）

Story 4.3: 银行卡管理功能测试（使用现有测试）

Story 4.4: 备注和回访功能测试（使用现有测试）

Story 4.5: 完整流程验证

Story 4.6: 稳定性测试（使用现有测试）

Epic 5: 完善文档与开发者体验

Story 5.1: 完善 README、API 文档和示例

epics.md 34 KB

Geçmiş Ham