# Story 4.1: 开发表单辅助工具函数

Status: ready-for-dev

## Story

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

## Acceptance Criteria

1. **fillMultiStepForm 函数实现** - 函数签名：`fillMultiStepForm(page, steps): Promise<void>`，支持分步填写表单
2. **scrollToSection 函数实现** - 滚动到特定区域，等待目标区域可见
3. **类型定义完整** - FormStep 接口、FieldTypes 类型、FormHelperOptions 配置
4. **错误处理** - 使用 E2ETestError 和 ErrorContext
5. **JSDoc 完整** - 包含 @param、@throws、@example


## Tasks / Subtasks

- [ ] **Task 1: 实现 fillMultiStepForm 函数** (AC: #1)
  - [ ] Subtask 1.1: 定义 FormStep 接口和 FieldTypes 类型
  - [ ] Subtask 1.2: 实现步骤遍历和字段填充逻辑
  - [ ] Subtask 1.3: 支持文本字段、选择器、日期字段
  - [ ] Subtask 1.4: 集成现有工具（selectRadixOption、uploadFileToField）

- [ ] **Task 2: 实现 scrollToSection 函数** (AC: #2)
  - [ ] Subtask 2.1: 通过 sectionName 定位区域
  - [ ] Subtask 2.2: 使用 scrollIntoViewIfNeeded() 滚动
  - [ ] Subtask 2.3: 等待目标区域可见

- [ ] **Task 3: 定义类型和配置** (AC: #3)
- [ ] **Task 4: 实现错误处理** (AC: #4)
- [ ] **Task 5: 添加 JSDoc 文档** (AC: #5)
- [ ] **Task 6: 更新主导出文件

## Dev Notes

### Epic 4 背景与目标

**Epic 4: 表单工具开发与验证**

遵循 Epic 2 和 Epic 3 的成功模式：工具开发 → 真实 E2E 测试验证 → 稳定性验证

**当前进度：**
- Epic 1: ✅ 已完成（类型定义、错误处理、Select 工具）
- Epic 2: ✅ 已完成（Select 工具 E2E 验证）
- Epic 3: ✅ 已完成（文件上传工具 + 稳定性验证）
- Epic 4: 🔄 本 Epic - 表单工具开发与验证

### Epic 2-3 成功模式经验

1. **"先验证再扩展"策略** - Epic 2/3 都遵循此模式并成功
2. **DOM 结构假设必须验证** - 单元测试无法发现真实 DOM 问题
3. **稳定性验证标准** - Epic 3 证明 6 次连续运行足够

### 架构文档参考

**核心函数签名：**
fillMultiStepForm(page: Page, steps: FormStep[]): Promise<void>
scrollToSection(page: Page, sectionName: string): Promise<void>

**类型定义设计：**
export interface FormStep { name: string; fields: FormField[]; }
export interface FormField { selector: string; type: FieldType; value: string | string[]; }
export type FieldType = "text" | "select" | "select-async" | "date" | "file" | "checkbox" | "radio";
export interface FormHelperOptions extends BaseOptions { stepDelay?: number; clearBeforeFill?: boolean; }


### 与现有工具的集成

复用已实现的工具：
- selectRadixOption / selectRadixOptionAsync - Select 工具
- uploadFileToField - 文件上传
- selectCascade - 级联选择（Epic 3 创建）

### 测试场景设计

**残疾人管理表单场景：**
await fillMultiStepForm(page, [{ name: "基本信息", fields: [{ selector: "name", type: "text", value: "测试用户" }] }]);
await scrollToSection(page, "照片");

### Epic 2-3 常见陷阱避免

1. DOM 结构假设必须验证 - 使用真实 E2E 测试
2. 避免硬编码超时 - 使用 Playwright auto-waiting
3. 精确文本匹配 - 使用 :text-is() 或 { exact: true }

### 参考文档

- [Source: _bmad-output/planning-artifacts/epics.md#Epic-4-Story-4.1]
- [Source: _bmad-output/planning-artifacts/architecture.md]
- [Source: _bmad-output/implementation-artifacts/epic-2-retrospective.md]
- [Source: _bmad-output/implementation-artifacts/epic-3-retrospective.md]

## Dev Agent Record

### Agent Model Used

claude-opus-4-5-20251101

### Completion Notes List

**创建日期:** 2026-01-11

**Story 分析完成:**
- ✅ 加载并分析了 Epic 4 完整需求
- ✅ 分析了 Epic 2-3 成功模式经验
- ✅ 提取了架构文档中的设计要求
- ✅ 定义了类型和函数签名
- ✅ 提供了实现示例和错误处理模式

**可以进入开发阶段 (Story 4.1 → ready-for-dev)**

### File List

**待创建文件:**
1. packages/e2e-test-utils/src/form-helper.ts - 表单辅助工具实现
2. packages/e2e-test-utils/tests/unit/form-helper.test.ts - 单元测试（Story 4.2）
3. packages/e2e-test-utils/src/index.ts - 更新主导出

---

**Story 状态:** ✅ ready-for-dev
**准备日期:** 2026-01-11