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

Status: ready-for-dev

Story

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

Acceptance Criteria

fillMultiStepForm 函数实现 - 函数签名：fillMultiStepForm(page, steps): Promise<void>，支持分步填写表单
scrollToSection 函数实现 - 滚动到特定区域，等待目标区域可见
类型定义完整 - FormStep 接口、FieldTypes 类型、FormHelperOptions 配置
错误处理 - 使用 E2ETestError 和 ErrorContext
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 成功模式经验

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

架构文档参考

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

类型定义设计： 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 常见陷阱避免

DOM 结构假设必须验证 - 使用真实 E2E 测试
避免硬编码超时 - 使用 Playwright auto-waiting
精确文本匹配 - 使用 :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

待创建文件:

packages/e2e-test-utils/src/form-helper.ts - 表单辅助工具实现
packages/e2e-test-utils/tests/unit/form-helper.test.ts - 单元测试（Story 4.2）
packages/e2e-test-utils/src/index.ts - 更新主导出

4-1-form-helper-tool.md 4.3 KB Cronologia Originale