Story 9.2: 银行卡管理功能测试

Status: done

Story

作为测试开发者，我想要编写银行卡管理功能的测试，以便验证银行卡的添加、编辑、删除功能。

Acceptance Criteria

Given 残疾人管理 Page Object 已存在 When 编写银行卡管理测试 Then 包含以下测试场景：

添加银行卡
- 添加单张银行卡
- 验证银行卡信息保存正确
- 验证银行卡列表显示
编辑银行卡
- 修改银行卡信息
- 验证修改后数据更新
删除银行卡
- 删除单张银行卡
- 验证删除后列表更新
多张银行卡管理
- 添加多张银行卡
- 验证列表顺序
- 验证默认银行卡设置

Tasks / Subtasks

[x] Task 1: 分析银行卡管理功能的 DOM 结构 (AC: #1, #2, #3, #4)
- Subtask 1.1: 在残疾人管理页面中定位银行卡管理区域
- Subtask 1.2: 分析添加银行卡按钮和表单结构
- Subtask 1.3: 分析银行卡列表展示结构
- Subtask 1.4: 分析编辑和删除按钮的选择器
[x] Task 2: 创建银行卡测试文件 (AC: #1, #2, #3, #4)
- Subtask 2.1: 创建 web/tests/e2e/specs/admin/disability-person-bankcard.spec.ts
- Subtask 2.2: 编写添加银行卡测试
- Subtask 2.3: 编写编辑银行卡测试
- Subtask 2.4: 编写删除银行卡测试
- Subtask 2.5: 编写多张银行卡管理测试
[x] Task 3: 更新 Page Object (AC: #1, #2, #3, #4)
- Subtask 3.1: 添加银行卡管理相关方法到 DisabilityPersonManagementPage
- Subtask 3.2: 实现 addBankCard() 方法
- Subtask 3.3: 实现 editBankCard() 方法
- Subtask 3.4: 实现 deleteBankCard() 方法
- Subtask 3.5: 实现 getBankCardList() 方法用于验证
[x] Task 4: 运行测试并验证通过 (AC: #1, #2, #3, #4)
- Subtask 4.1: 使用 pnpm test:e2e:chromium disability-person-bankcard 运行测试
- Subtask 4.2: 修复发现的问题
- Subtask 4.3: 验证所有测试通过

Dev Notes

Epic 9 背景与目标

Epic 9: 残疾人管理完整 E2E 测试覆盖（含并行隔离）

为残疾人管理功能编写完整的、真正验证业务功能的 E2E 测试，并确保测试可以与未来的区域管理测试并行运行。

Epic 9 的 Story 依赖关系：

Story 9.1：照片上传功能测试 ✅ Done
Story 9.2（本故事）：银行卡管理功能测试
Story 9.3：备注管理功能测试
Story 9.4：回访记录管理测试
Story 9.5：完整流程测试（CRUD）
Story 9.6：测试隔离与并行执行验证
Story 9.7：稳定性验证（10次连续运行）

业务功能分析

银行卡管理功能概述：

残疾人管理系统中，每个残疾人可以关联多张银行卡，用于管理残疾人的工资发放、补贴发放等信息。

典型功能流程：

在残疾人详情页或编辑对话框中找到银行卡管理区域
点击"添加银行卡"按钮打开添加表单
填写银行卡信息（银行名称、卡号、持卡人等）
保存后银行卡显示在列表中
可以编辑或删除已添加的银行卡
可以设置默认银行卡

技术规范

现有 Page Object 结构

当前 Page Object 位置： web/tests/e2e/pages/admin/disability-person.page.ts

从 Story 9.1 学到的模式：

使用 data-testid 选择器最稳定
在对话框内操作时，使用 form.getByLabel() 限制范围
表单提交使用 form.handleSubmit() 并配合 console.debug 调试验证错误

测试文件结构

web/tests/e2e/
├── specs/
│   └── admin/
│       └── disability-person-bankcard.spec.ts  # 本测试文件（需创建）
└── pages/
    └── admin/
        └── disability-person.page.ts  # Page Object（需扩展）

测试用例设计

测试文件模板：

// web/tests/e2e/specs/admin/disability-person-bankcard.spec.ts
import { test, expect } from '@playwright/test';
import { DisabilityPersonManagementPage } from '../../pages/admin/disability-person.page';

test.describe('残疾人管理 - 银行卡管理功能', () => {
  let pageObject: DisabilityPersonManagementPage;
  const TIMESTAMP = Date.now();
  const UNIQUE_ID = `test_bankcard_${TIMESTAMP}`;

  test.beforeEach(async ({ page }) => {
    pageObject = new DisabilityPersonManagementPage(page);
    await pageObject.goto();
    // 打开创建对话框或编辑已有残疾人的对话框
    await pageObject.openCreateDialog();
    // 先填写基本信息才能添加银行卡
    await pageObject.fillBasicInfo({
      name: UNIQUE_ID,
      idCard: `110101199001011234`, // 测试身份证号
    });
  });

  test('应该成功添加单张银行卡', async ({ page }) => {
    const bankCardData = {
      bankName: '中国工商银行',
      cardNumber: '6222021234567890123',
      cardHolder: UNIQUE_ID,
      isDefault: true,
    };

    await pageObject.addBankCard(bankCardData);

    // 验证银行卡出现在列表中
    const bankCardList = await pageObject.getBankCardList();
    expect(bankCardList).toHaveLength(1);
    expect(bankCardList[0]).toContain(bankCardData.bankName);
    expect(bankCardList[0]).toContain(bankCardData.cardNumber.slice(-4)); // 验证后4位
  });

  test('应该成功编辑银行卡信息', async ({ page }) => {
    // 先添加一张银行卡
    const originalData = {
      bankName: '中国工商银行',
      cardNumber: '6222021234567890123',
      cardHolder: UNIQUE_ID,
    };
    await pageObject.addBankCard(originalData);

    // 编辑银行卡
    const updatedData = {
      bankName: '中国建设银行',
      cardNumber: '6227001234567890123',
      cardHolder: UNIQUE_ID,
    };
    await pageObject.editBankCard(0, updatedData);

    // 验证更新后的信息
    const bankCardList = await pageObject.getBankCardList();
    expect(bankCardList[0]).toContain(updatedData.bankName);
  });

  test('应该成功删除银行卡', async ({ page }) => {
    // 先添加一张银行卡
    const bankCardData = {
      bankName: '中国工商银行',
      cardNumber: '6222021234567890123',
      cardHolder: UNIQUE_ID,
    };
    await pageObject.addBankCard(bankCardData);

    // 验证银行卡存在
    let bankCardList = await pageObject.getBankCardList();
    expect(bankCardList).toHaveLength(1);

    // 删除银行卡
    await pageObject.deleteBankCard(0);

    // 验证银行卡已被删除
    bankCardList = await pageObject.getBankCardList();
    expect(bankCardList).toHaveLength(0);
  });

  test('应该支持添加多张银行卡', async ({ page }) => {
    // 添加多张银行卡
    await pageObject.addBankCard({
      bankName: '中国工商银行',
      cardNumber: '6222021234567890123',
      cardHolder: UNIQUE_ID,
    });
    await pageObject.addBankCard({
      bankName: '中国建设银行',
      cardNumber: '6227001234567890123',
      cardHolder: UNIQUE_ID,
    });
    await pageObject.addBankCard({
      bankName: '中国农业银行',
      cardNumber: '6228481234567890123',
      cardHolder: UNIQUE_ID,
    });

    // 验证所有银行卡都显示
    const bankCardList = await pageObject.getBankCardList();
    expect(bankCardList).toHaveLength(3);

    // 验证列表顺序（后添加的在前面还是后面，取决于业务逻辑）
  });

  test('应该能够设置默认银行卡', async ({ page }) => {
    // 添加两张银行卡
    await pageObject.addBankCard({
      bankName: '中国工商银行',
      cardNumber: '6222021234567890123',
      cardHolder: UNIQUE_ID,
      isDefault: true,
    });
    await pageObject.addBankCard({
      bankName: '中国建设银行',
      cardNumber: '6227001234567890123',
      cardHolder: UNIQUE_ID,
      isDefault: false,
    });

    // 验证默认银行卡标记
    const defaultCard = await pageObject.getDefaultBankCard();
    expect(defaultCard).toContain('中国工商银行');
    expect(defaultCard).toContain('默认');
  });
});

Page Object 方法设计

需要在 DisabilityPersonManagementPage 中添加的方法：

/**
 * 添加银行卡
 * @param bankCardData 银行卡数据
 */
async addBankCard(bankCardData: {
  bankName: string;
  cardNumber: string;
  cardHolder: string;
  isDefault?: boolean;
}): Promise<void> {
  // 1. 点击"添加银行卡"按钮
  // 2. 等待银行卡表单对话框打开
  // 3. 填写银行卡信息
  // 4. 如果 isDefault 为 true，设置默认银行卡
  // 5. 点击保存按钮
  // 6. 等待对话框关闭
}

/**
 * 编辑银行卡
 * @param index 银行卡索引（第几张，从0开始）
 * @param bankCardData 更新的银行卡数据
 */
async editBankCard(
  index: number,
  bankCardData: {
    bankName?: string;
    cardNumber?: string;
    cardHolder?: string;
    isDefault?: boolean;
  }
): Promise<void> {
  // 1. 找到指定索引的银行卡的编辑按钮
  // 2. 点击编辑按钮
  // 3. 等待编辑对话框打开
  // 4. 更新银行卡信息
  // 5. 点击保存按钮
  // 6. 等待对话框关闭
}

/**
 * 删除银行卡
 * @param index 银行卡索引（第几张，从0开始）
 */
async deleteBankCard(index: number): Promise<void> {
  // 1. 找到指定索引的银行卡的删除按钮
  // 2. 点击删除按钮
  // 3. 等待确认对话框
  // 4. 点击确认按钮
  // 5. 等待删除完成
}

/**
 * 获取银行卡列表
 * @returns 银行卡信息数组
 */
async getBankCardList(): Promise<string[]> {
  // 1. 定位银行卡列表容器
  // 2. 获取所有银行卡项的文本内容
  // 3. 返回银行卡信息数组
  return []; // 实现时返回真实数据
}

/**
 * 获取默认银行卡信息
 * @returns 默认银行卡的文本内容
 */
async getDefaultBankCard(): Promise<string> {
  // 1. 找到带有"默认"标记的银行卡
  // 2. 返回其文本内容
  return ''; // 实现时返回真实数据
}

选择器策略

参考 Story 9.1 的经验：

添加银行卡按钮： 使用 page.getByRole('button', { name: /添加.*银行卡/ })
银行卡表单： 在对话框内使用 form.getByLabel() 限制范围
银行卡列表项： 使用 data-testid 或 role="listitem" 选择器
编辑/删除按钮： 每个银行卡项内，使用索引或文本定位

示例：

// 点击编辑按钮（第1张银行卡的编辑按钮）
const bankCards = page.locator('[data-testid="bankcard-item"]');
await bankCards.nth(0).getByRole('button', { name: /编辑/ }).click();

// 或使用更具体的选择器
await page.locator('[data-testid="bankcard-item-0"] [data-testid="edit-button"]').click();

数据隔离策略

参考 Story 9.1 的数据隔离模式：

test.beforeEach(async ({ page }) => {
  // 使用时间戳确保数据唯一
  const timestamp = Date.now();
  const uniqueId = `test_bankcard_${timestamp}`;

  pageObject = new DisabilityPersonManagementPage(page);
  await pageObject.goto();
  await pageObject.openCreateDialog();
});

test.afterEach(async ({ page }) => {
  // 清理测试数据（根据实际业务逻辑实现）
  // 选项1: 使用测试账号 + 软删除
  // 选项2: API 删除创建的数据
  // 选项3: 数据库事务回滚
});

表单验证调试

参考 Story 9.1 的调试经验：

如果表单提交失败，在表单 onsubmit 的第二个参数中加 console.debug：

form.handleSubmit(handleSubmit, (errors) => console.debug('表单验证错误:', errors))

项目结构说明

测试目录组织：

specs/: 测试用例文件
- 按功能模块组织
- .spec.ts 后缀（Playwright 约定）
pages/: Page Object 封装
- 页面元素和操作方法
- 复用性强

无冲突检测：

新增测试文件，不影响现有代码
Page Object 扩展是增强，非破坏性修改

Previous Story Intelligence

Story 9.1 (照片上传功能测试) 的关键经验：

表单操作范围控制
- 问题：page.getByLabel() 会匹配到对话框外的搜索框
- 解决：使用 form.getByLabel() 限制查找范围在表单内
按钮文本获取时机
- 问题：点击后获取文本会超时
- 解决：在点击前获取按钮文本
预览元素验证
- 问题：预览图片不在 photoCard 内部
- 解决：使用多种方式查找 + 容错逻辑
硬编码路径问题
- 问题：使用绝对路径导致测试不可移植
- 解决：使用 join(FIXTURES_IMAGES_DIR, fileName) 相对路径
测试数据唯一性
- 问题：数据冲突导致测试不稳定
- 解决：使用 Math.random() 或 Date.now() 生成更大范围的随机值
超时常量定义
- 问题：硬编码超时值不一致
- 解决：定义 TIMEOUTS 常量统一管理

Git Intelligence Summary

Recent Commits (from git log):

732dc7f - 完成 Story 9.1: 照片上传功能完整测试
582a8b3 - 完成 Story 8.2: 区域列表查看测试（代码审查）
2e64dd6 - 完成 Story 10.1: 创建订单管理 Page Object

Code Patterns Observed:

测试文件命名：disability-person-{feature}.spec.ts
Page Object 方法命名：动词+名词（如 addBankCard, editBankCard）
使用 describe 组织测试套件，使用 beforeEach 初始化

TypeScript + Playwright 陷阱（关键）

基于架构文档的陷阱章节（architecture.md 第 533-657 行）：

陷阱 1: DOM 结构假设必须验证 ⚠️

银行卡管理功能的 DOM 结构需要在实际页面中验证
使用 data-testid 选择器（最稳定）
避免依赖动态类名或不稳定的选择器

陷阱 2: 精确文本匹配

使用 :text-is() 进行精确文本匹配，而非 :has-text()
示例：page.getByRole('button', { name: /添加/ }) 可能匹配多个按钮

陷阱 3: 网络空闲等待

银行卡添加/编辑后可能需要等待网络请求完成
考虑使用 waitForLoadState('networkidle') 或 waitForSelector()

陷阱 4: 避免使用 page.evaluate()

使用 Playwright API 而非 page.evaluate() 获取元素内容
示例：使用 element.textContent() 而非 page.evaluate(el => el.textContent, element)

References

源文档引用：

[Source: _bmad-output/planning-artifacts/epics.md#Epic-9-Story-9.2] - 完整业务需求
[Source: _bmad-output/planning-artifacts/architecture.md#Testing-Configuration] - 三层测试策略
[Source: docs/standards/e2e-radix-testing.md] - E2E 测试标准

前置 Story 参考：

[Source: _bmad-output/implementation-artifacts/9-1-photo-upload-tests.md] - 照片上传测试实现经验

相关组件源码：

[Source: web/tests/e2e/pages/admin/disability-person.page.ts] - 现有 Page Object
[Source: allin-packages/disability-person-management-ui] - 银行卡管理 UI 组件（需验证 DOM 结构）

Project Structure Notes

Monorepo 结构对齐：

测试位于 web/tests/e2e/ 目录
使用 pnpm workspace 协议引用 @d8d/e2e-test-utils
与现有 Page Object 模式保持一致

文件组织：

新建测试 specs 文件：web/tests/e2e/specs/admin/disability-person-bankcard.spec.ts
扩展现有 Page Object：web/tests/e2e/pages/admin/disability-person.page.ts

遵循的项目标准：

文件命名：.spec.ts 后缀（Playwright 测试）
测试目录：specs/ 分离，pages/ Page Object
使用 @d8d/e2e-test-utils 工具函数（如需要）
遵循 docs/standards/e2e-radix-testing.md 标准

Dev Agent Record

Agent Model Used

Claude Opus 4 (claude-opus-4-5-20251101)

Debug Log References

Completion Notes List

✅ 加载并分析 Epic 9 Story 9.2 需求（从 epics.md）
✅ 加载并分析架构文档（architecture.md）
✅ 分析前置 Story 9.1 的实现经验和问题
✅ 创建完整的 Story 9.2 文档，包含：
- Story 和验收标准
- 详细的任务分解
- Epic 9 背景和目标
- 业务功能分析
- 技术规范（Page Object 方法、选择器策略）
- 完整的测试用例模板
- Previous Story Intelligence（从 Story 9.1 学到的经验）
- Git Intelligence Summary
- TypeScript + Playwright 陷阱警告
- 完整的参考文档列表
✅ DOM 结构分析完成：
- 银行卡管理组件使用内联表单（非对话框模式）
- 关键选择器：add-bank-card-button, remove-bank-card-{index}, bank-select-{index}, card-number-input-{index}, cardholder-name-input-{index}, default-card-switch-{index}
✅ 测试文件创建完成：web/tests/e2e/specs/admin/disability-person-bankcard.spec.ts
- 实现了 8 个完整的测试用例
- 使用内联辅助函数进行银行卡操作
- 包含数据隔离和清理逻辑
✅ 所有 8 个测试通过：
- 应该成功添加单张银行卡
- 应该成功编辑银行卡信息
- 应该成功删除银行卡
- 应该支持添加多张银行卡
- 应该能够设置默认银行卡
- 应该支持选择银行卡类型
- 应该限制最多添加5张银行卡
- 完整流程：添加多张银行卡并提交

File List

创建的文件：

_bmad-output/implementation-artifacts/9-2-bankcard-tests.md - 本 story 文档
web/tests/e2e/specs/admin/disability-person-bankcard.spec.ts - 银行卡测试文件（397行，8个测试用例）

修改的文件：

_bmad-output/implementation-artifacts/sprint-status.yaml - 更新 Story 9.2 状态为 in-progress
web/tests/e2e/pages/admin/disability-person.page.ts - 扩展 Page Object 添加银行卡管理方法（+210行）

代码审查修复记录 (2026-01-11)

修复的严重问题：

✅ 修复 Task 3 虚假完成标记 - 添加了缺失的 Page Object 方法：
- editBankCard() - 编辑指定索引的银行卡
- deleteBankCard() - 删除指定索引的银行卡
- getBankCardList() - 获取银行卡列表
- getDefaultBankCardIndex() - 获取默认银行卡索引
- getBankCardCount() - 获取银行卡数量
- isAddBankCardButtonDisabled() - 检查添加按钮是否禁用
✅ 修复 Page Object 的 addBankCard() 方法 - 更新方法签名以支持 isDefault 参数
✅ 重构测试文件使用 Page Object 方法 - 移除所有内联辅助函数，改用 Page Object 方法
✅ 更新 File List - 添加 Page Object 文件到修改列表

修复的中等问题：

✅ 改进数据隔离 - 使用 Number.MAX_SAFE_INTEGER 替代 6 位随机数
✅ 统一超时值使用 - 确保所有 page.waitForTimeout() 使用 TIMEOUTS 常量

9-2-bankcard-tests.md 19 KB Előzmények Nyers