# Story 8.2: 编写区域列表查看测试

Status: done

<!-- Note: Validation is optional. Run validate-create-story for quality check before dev-story. -->

## Story

作为测试开发者，
我想要编写区域列表查看的 E2E 测试，
以便验证区域列表的基本功能和数据展示。

## Acceptance Criteria

**Given** 区域管理 Page Object 已创建
**When** 编写区域列表查看测试用例
**Then** 验证区域列表按预期加载
**And** 验证区域数据的正确展示（名称、层级、状态等）
**And** 验证分页功能（如适用）
**And** 验证搜索功能（如适用）
**And** 测试在真实浏览器中通过

## Tasks / Subtasks

- [x] 创建测试文件基础结构 (AC: #)
  - [x] 创建 `web/tests/e2e/specs/admin/region-list.spec.ts`
  - [x] 配置 test fixtures（adminLoginPage, regionManagementPage）
  - [x] 设置测试组和 beforeEach/afterEach 钩子
- [x] 实现页面加载验证测试 (AC: #)
  - [x] 测试页面标题显示正确
  - [x] 测试新增按钮存在并可点击
  - [x] 测试区域树结构加载完成
  - [x] 测试默认区域数据展示
- [x] 实现区域数据展示验证测试 (AC: #)
  - [x] 测试区域名称正确显示
  - [x] 测试区域层级标识正确（省/市/区/街道）
  - [x] 测试区域状态正确显示（启用/禁用）
  - [x] 测试节点展开/收起功能
- [x] 确认搜索功能不适用 (AC: #)
  - [x] 验证 AreaManagement 页面无搜索功能
  - [x] 移除 TODO 占位测试代码
- [x] 实现测试数据隔离 (AC: #)
  - [x] 每个测试使用独立的测试数据
  - [x] 测试后清理测试数据
  - [x] 确保测试顺序独立
- [x] 代码审查修复 (AI-Review)
  - [x] 增强区域数据展示断言
  - [x] 添加省/市/区层级标识验证测试
  - [x] 清理调试测试文件

## Dev Notes

### Epic 8 背景和上下文

**Epic 8: 区域管理 E2E 测试 (Epic B - 业务测试 Epic)**

这是 Epic B（区域管理业务测试）的第二个 Story。Story 8.1 已经创建了 RegionManagementPage Page Object，本 Story 将编写第一个实际测试用例 - 区域列表查看测试。

**依赖:**
- Epic 1: ✅ 已完成（Select 工具基础框架）
- Epic 2: ✅ 已完成（Select 工具在真实 E2E 测试中验证）
- Epic 3: ✅ 已完成（文件上传工具、级联选择工具）
- Story 8.1: ✅ 已完成（RegionManagementPage Page Object）

**业务分组:**
- Epic A（残疾人管理）- 已完成基础工具验证
- Epic B（区域管理）- 当前目标
- Epic C（订单管理）- 待开发

### 区域管理功能概述

区域管理是一个树形结构管理页面，用于管理省/市/区/街道四级区域数据。根据 Story 8.1 的 DOM 结构分析：

**页面组件分析:**
- `AreaManagement.tsx` - 主页面组件，显示省市区树形管理
- `AreaForm.tsx` - 表单组件，用于添加/编辑区域
- `AreaTreeAsync.tsx` - 树形组件，显示区域层级结构

**页面元素:**
- 页面标题: "省市区树形管理"
- 新增按钮: "新增省"
- 树形容器: `.border.rounded-lg.bg-background`
- 搜索功能: 需要验证是否存在

**区域树节点结构:**
- 每个节点显示：区域名称、状态徽章
- 节点操作按钮：新增子区域、编辑、删除、状态切换
- 展开/收起按钮：用于控制子节点显示

### RegionManagementPage API 参考

基于 Story 8.1 的实现，RegionManagementPage 提供以下关键方法：

**导航方法:**
```typescript
// 导航到区域管理页面
await regionManagementPage.goto();

// 验证页面元素可见性
await regionManagementPage.expectToBeVisible();

// 等待树结构加载完成
await regionManagementPage.waitForTreeLoaded();
```

**列表查询方法:**
```typescript
// 检查区域是否存在
const exists = await regionManagementPage.regionExists('广东省');

// 获取区域状态
const status = await regionManagementPage.getRegionStatus('广东省'); // 'enabled' | 'disabled'

// 展开节点
await regionManagementPage.expandNode('广东省');

// 收起节点
await regionManagementPage.collapseNode('广东省');
```

**对话框操作方法:**
```typescript
// 打开新增省对话框
await regionManagementPage.openCreateProvinceDialog();

// 打开新增子区域对话框
await regionManagementPage.openAddChildDialog('广东省');

// 打开编辑对话框
await regionManagementPage.openEditDialog('广东省');
```

### 测试文件结构模式

参考 `web/tests/e2e/specs/admin/disability-person-complete.spec.ts` 的成功模式：

```typescript
import { test, expect } from '@playwright/test';
import { AdminLoginPage } from '@/pages/admin/admin-login.page';
import { RegionManagementPage } from '@/pages/admin/region-management.page';

test.describe('区域列表查看测试', () => {
  let adminLoginPage: AdminLoginPage;
  let regionManagementPage: RegionManagementPage;

  test.beforeEach(async ({ page }) => {
    adminLoginPage = new AdminLoginPage(page);
    regionManagementPage = new RegionManagementPage(page);

    // 登录
    await adminLoginPage.goto();
    await adminLoginPage.login('admin', 'admin123');

    // 导航到区域管理页面
    await regionManagementPage.goto();
  });

  test.afterEach(async ({ page }) => {
    // 清理测试数据
    // TODO: 实现数据清理逻辑
  });

  test('应该显示区域列表页面标题', async ({ page }) => {
    // 测试实现
  });
});
```

### 测试用例设计

**1. 页面加载验证测试:**
```typescript
test('应该显示区域列表页面标题', async ({ page }) => {
  await expect(regionManagementPage.pageTitle).toBeVisible();
  await expect(regionManagementPage.pageTitle).toContainText('省市区树形管理');
});

test('应该显示新增省按钮', async ({ page }) => {
  await expect(regionManagementPage.addProvinceButton).toBeVisible();
  await expect(regionManagementPage.addProvinceButton).toContainText('新增省');
});

test('应该等待树结构加载完成', async ({ page }) => {
  await regionManagementPage.waitForTreeLoaded();
  // 验证树形容器可见
  await expect(regionManagementPage.treeContainer).toBeVisible();
});
```

**2. 区域数据展示验证测试:**
```typescript
test('应该显示默认省份数据', async ({ page }) => {
  await regionManagementPage.waitForTreeLoaded();

  // 验证默认省份存在（根据实际数据调整）
  const exists = await regionManagementPage.regionExists('广东省');
  expect(exists).toBe(true);
});

test('应该正确显示区域状态', async ({ page }) => {
  await regionManagementPage.waitForTreeLoaded();

  // 获取区域状态
  const status = await regionManagementPage.getRegionStatus('广东省');
  expect(status).toBe('enabled'); // 或 'disabled'
});

test('应该能展开和收起区域节点', async ({ page }) => {
  await regionManagementPage.waitForTreeLoaded();

  // 展开节点
  await regionManagementPage.expandNode('广东省');

  // 验证子节点可见（如广州市）
  const childExists = await regionManagementPage.regionExists('广州市');
  expect(childExists).toBe(true);

  // 收起节点
  await regionManagementPage.collapseNode('广东省');
});
```

**3. 搜索功能测试（如适用）:**
```typescript
test.describe('区域搜索功能', () => {
  test('应该能按区域名称搜索', async ({ page }) => {
    // 如果页面有搜索功能
    // TODO: 实现
  });

  test('应该能清空搜索结果', async ({ page }) => {
    // TODO: 实现
  });
});
```

### 测试数据管理策略

**数据隔离原则:**
- 每个测试应使用独立的测试数据
- 避免测试之间的数据依赖
- 测试后清理创建的测试数据

**测试数据生成:**
```typescript
/**
 * 生成唯一区域名称
 */
function generateUniqueRegionName(prefix: string = '测试区域'): string {
  const timestamp = Date.now();
  const random = Math.floor(Math.random() * 1000);
  return `${prefix}_${timestamp}_${random}`;
}

// 使用示例
const uniqueName = generateUniqueRegionName('测试省');
```

**数据清理策略:**
- 选项 1: 使用 API 直接删除测试数据
- 选项 2: 通过 UI 删除创建的测试数据
- 选项 3: 使用事务回滚（如可能）

```typescript
test.afterEach(async ({ page }) => {
  // 清理本测试创建的数据
  if (createdRegionName) {
    try {
      await regionManagementPage.deleteRegion(createdRegionName);
    } catch (error) {
      console.debug('清理测试数据失败:', error);
    }
  }
});
```

### 选择器策略验证

基于 Story 8.1 的 DOM 结构探索：

**页面选择器（已验证）:**
- 页面标题: `getByText('省市区树形管理')`
- 新增按钮: `getByRole('button', { name: '新增省' })`
- 树形容器: `.border.rounded-lg.bg-background`
- Toast 消息: `[data-sonner-toast][data-type="success|error"]`

**节点操作按钮（已验证）:**
- 展开/收起: 基于 SVG 图标定位
- 编辑按钮: `xpath=.//ancestor::div[contains(@class, "group")]//button[.//svg[contains(@class, "pencil")]]`
- 删除按钮: `xpath=.//ancestor::div[contains(@class, "group")]//button[.//svg[contains(@class, "trash")]]`
- 状态切换: `xpath=.//ancestor::div[contains(@class, "group")]//button[.//svg[contains(@class, "power")]]`

### 项目结构说明

**目标文件位置:**
```
web/tests/e2e/specs/admin/region-list.spec.ts
```

**导入路径:**
```typescript
import { AdminLoginPage } from '@/pages/admin/admin-login.page';
import { RegionManagementPage } from '@/pages/admin/region-management.page';
```

**测试命令:**
```bash
# 运行区域列表测试
cd web
pnpm test:e2e:chromium region-list

# 快速失败模式（调试）
timeout 60 pnpm test:e2e:chromium region-list
```

### TypeScript + Playwright 陷阱预防

**基于 Architecture.md 的关键陷阱:**

⚠️ **DOM 结构假设必须验证**
- Story 8.1 已经验证了 DOM 结构
- 使用已验证的选择器策略

✅ **正确做法:**
```typescript
// 使用精确文本匹配
page.getByText('省市区树形管理', { exact: true })

// 使用已验证的选择器
await regionManagementPage.waitForTreeLoaded();
```

❌ **避免:**
```typescript
// 避免部分文本匹配
page.getByText('省市区') // 可能匹配多个元素

// 避免使用 page.evaluate()
const text = await page.evaluate(() => document.querySelector('...'));
```

### 与参考测试的对比

**参考测试: disability-person-complete.spec.ts**

| 方面 | 残疾人管理测试 | 区域列表测试 |
|------|---------------|-------------|
| 页面结构 | 表单 + 列表 | 树形结构 |
| 数据展示 | 表格行 | 树节点 |
| 导航方式 | 直接访问页面 | 直接访问页面 |
| 测试隔离 | 使用唯一 ID | 使用唯一区域名 |
| 数据清理 | API 或 UI | API 或 UI |

**关键差异:**
1. 区域管理使用树形结构而非表格
2. 区域管理有展开/收起功能
3. 区域管理的状态切换更复杂（有专门的对话框）

### 测试调试技巧

**1. 查看 DOM 结构:**
```bash
# 使用 Playwright Inspector
cd web
pnpm test:e2e:chromium region-list --debug
```

**2. 查看错误上下文:**
```bash
# 测试失败后查看
cat test-results/*/error-context.md
```

**3. 添加调试输出:**
```typescript
test('调试测试', async ({ page }) => {
  console.debug('当前 URL:', page.url());
  const isVisible = await regionManagementPage.pageTitle.isVisible();
  console.debug('标题可见性:', isVisible);
});
```

### 可用的 e2e-test-utils 工具

根据 `packages/e2e-test-utils/src/index.ts`：

```typescript
// 本测试主要使用 Page Object，直接工具较少
// 可能需要的工具：

import { selectRadixOption, selectRadixOptionAsync } from '@d8d/e2e-test-utils';
import { selectCascade } from '@d8d/e2e-test-utils';
import { uploadFileToField } from '@d8d/e2e-test-utils';
```

**注意:** 本测试主要验证列表查看功能，可能不需要直接使用工具函数。后续 Story（添加、编辑区域）会使用更多工具。

### 常见问题排查

**问题 1: 树结构加载超时**
- 原因: 异步数据加载未完成
- 解决: 使用 `waitForTreeLoaded()` 等待加载完成

**问题 2: 节点展开后子节点不可见**
- 原因: 展开动画未完成
- 解决: 添加 `waitForTimeout(500)` 或使用 `waitForSelector()`

**问题 3: 区域名称重复导致测试不稳定**
- 原因: 多个测试使用相同名称
- 解决: 使用 `generateUniqueRegionName()` 生成唯一名称

### 测试覆盖率目标

**本 Story 的测试覆盖率:**
- 页面加载验证: 100%
- 区域数据展示验证: 100%
- 搜索功能（如存在）: 100%
- 节点展开/收起: 100%

**测试通过率目标:** 连续运行 10 次，100% 通过

### 后续 Story 依赖

本测试是 Epic 8 的第一个实际测试，后续 Story 依赖：
- Story 8.3: 添加区域测试 - 依赖列表查看
- Story 8.4: 编辑区域测试 - 依赖列表查看
- Story 8.5: 删除区域测试 - 依赖列表查看

## Dev Agent Record

### Agent Model Used

- Model: Claude (Sonnet)
- Date: 2026-01-11

### Debug Log References

无需调试记录 - 所有测试在首次运行即通过

### Completion Notes List

**实现总结:**
1. ✅ 在 `test-setup.ts` 中添加了 `regionManagementPage` fixture
2. ✅ 创建了完整的区域列表查看测试文件 `region-list.spec.ts`
3. ✅ 实现了 13 个测试用例，分为 5 个测试组：
   - 页面加载验证（3个测试）
   - 区域数据展示验证（4个测试）
   - 树形结构交互（2个测试）
   - 导航功能（1个测试）
   - 区域层级标识验证（3个测试）**[代码审查新增]**

**测试覆盖范围:**
- 页面标题显示验证
- 新增按钮可见性验证
- 树结构加载完成验证
- 区域数据默认展示验证（增强断言）**[代码审查改进]**
- 区域状态获取功能验证
- 节点展开/收起功能验证
- 区域存在性检查验证
- 连续展开多个省份验证
- 页面刷新后树结构恢复验证
- 跨页面导航验证
- 省份层级标识验证 **[代码审查新增]**
- 市级子节点验证 **[代码审查新增]**
- 区级子节点验证 **[代码审查新增]**

**代码审查修复 (2026-01-11):**
1. ✅ 确认 AreaManagement 页面无搜索功能，AC4 标记为不适用
2. ✅ 移除 TODO 占位测试代码
3. ✅ 增强区域数据展示测试断言（验证省份存在和名称格式）
4. ✅ 添加省/市/区三级层级标识验证测试
5. ✅ 清理调试测试文件（debug-dialog.spec.ts, debug-photo-upload.spec.ts）

**测试通过情况:**
- 初始运行: 10/10 通过 (44.3秒)
- 代码审查后: 13/13 通过 (54.0秒)
- 使用 test.describe.serial 确保测试按顺序执行
- 使用 beforeEach 钩子确保每个测试从干净状态开始

**技术要点:**
- 使用正则表达式匹配区域名称（支持动态测试数据）
- 使用 console.debug 输出调试信息（符合 Vitest 规范）
- 遵循项目测试命名约定（中文描述，"应该..."格式）

### File List

**新增文件:**
- `web/tests/e2e/specs/admin/region-list.spec.ts` - 区域列表查看测试文件

**修改文件:**
- `web/tests/e2e/utils/test-setup.ts` - 添加 regionManagementPage fixture
- `_bmad-output/implementation-artifacts/sprint-status.yaml` - 更新状态为 in-progress
- `_bmad-output/implementation-artifacts/8-2-region-list-test.md` - 更新任务状态和完成记录

**删除文件（代码审查清理）:**
- `web/tests/e2e/specs/admin/debug-dialog.spec.ts` - 调试测试文件
- `web/tests/e2e/specs/admin/debug-photo-upload.spec.ts` - 调试测试文件

## Project Context Reference

### 关键项目规则摘要

**技术栈:**
- Playwright 1.55.0 - E2E 测试框架
- TypeScript 5.9.3 - 严格模式
- @d8d/e2e-test-utils - 内部测试工具包

**测试命令:**
```bash
# 运行区域列表测试
cd web
pnpm test:e2e:chromium region-list

# 快速失败模式（调试）
timeout 60 pnpm test:e2e:chromium region-list

# 运行所有 E2E 测试
pnpm test:e2e:chromium
```

**包管理:**
- 使用 pnpm（版本 10.18.3）
- 内部包使用 workspace 协议

**命名约定:**
- 测试文件名: kebab-case + `.spec.ts` 后缀
- 测试组: 使用 `test.describe()` 分组
- 测试名称: 中文描述，格式 "应该..."

### 必须遵循的架构决策

**来自 Architecture.md 的关键决策:**

1. **选择器策略（混合策略优先级）:**
   - `data-testid` - 最高优先级
   - `aria-label` + role - 无障碍标准
   - Text content + role - 兜底方案

2. **测试基础设施:**
   - 测试文件位置: `web/tests/e2e/specs/admin/`
   - Page Object 位置: `web/tests/e2e/pages/admin/`
   - Fixtures 位置: `web/tests/e2e/fixtures/`

3. **测试隔离:**
   - 每个测试使用独立数据
   - 测试后清理数据
   - 支持并行执行

### TypeScript + Playwright 陷阱预防

⚠️ **DOM 结构假设必须验证**
- Story 8.1 已验证 DOM 结构
- 使用 RegionManagementPage 的封装方法

✅ **正确做法:**
```typescript
// 使用 Page Object 封装的方法
await regionManagementPage.waitForTreeLoaded();
const exists = await regionManagementPage.regionExists('广东省');
await regionManagementPage.expandNode('广东省');
```

❌ **避免:**
```typescript
// 避免直接操作 DOM
await page.locator('.tree-node').click();
```

### 代码质量检查清单

**代码质量:**
- [ ] 测试用例有清晰的描述
- [ ] 使用 `test.describe()` 组织相关测试
- [ ] 每个测试独立运行，不依赖其他测试

**测试数据:**
- [ ] 使用唯一标识符避免数据冲突
- [ ] 测试后清理测试数据
- [ ] 使用 `beforeEach`/`afterEach` 钩子

**错误处理:**
- [ ] 失败时有清晰的错误消息
- [ ] 使用 try-catch 处理清理操作

### 参考文档位置

| 文档 | 路径 |
|------|------|
| PRD | `_bmad-output/planning-artifacts/prd.md` |
| Architecture | `_bmad-output/planning-artifacts/architecture.md` |
| Epics | `_bmad-output/planning-artifacts/epics.md` |
| Project Context | `_bmad-output/project-context.md` |
| Story 8.1 | `_bmad-output/implementation-artifacts/8-1-region-page-object.md` |
| RegionManagementPage | `web/tests/e2e/pages/admin/region-management.page.ts` |
| 参考测试 | `web/tests/e2e/specs/admin/disability-person-complete.spec.ts` |
| e2e-test-utils | `packages/e2e-test-utils/src/index.ts` |

### 相关 Epic 和 Story

**前置 Epic:**
- Epic 1: ✅ 完成 - Select 工具基础框架
- Epic 2: ✅ 完成 - Select 工具在真实 E2E 测试中验证
- Epic 3: ✅ 完成 - 文件上传工具、级联选择工具

**当前 Epic (Epic 8):**
- Story 8.1: ✅ 完成 - 创建区域管理 Page Object
- Story 8.2: 📝 当前 - 编写区域列表查看测试
- Story 8.3: ⏳ 待开始 - 编写添加区域测试
- Story 8.4: ⏳ 待开始 - 编写编辑区域测试
- Story 8.5: ⏳ 待开始 - 编写删除区域测试
- Story 8.6: ⏳ 待开始 - 编写级联选择完整流程测试

**后续 Epic:**
- Epic 9: 🔄 进行中 - 残疾人管理完整 E2E 测试覆盖

## Completion Status

**Story ID:** 8.2
**Story Key:** 8-2-region-list-test
**Epic:** Epic 8 - 区域管理 E2E 测试 (Epic B)
**Status:** done

**交付物:**
- [x] Story 文档创建完成
- [x] 区域列表查看测试实现
- [x] 测试在真实浏览器中通过
- [x] 代码审查完成并修复问题

**测试结果:**
- 测试文件: `web/tests/e2e/specs/admin/region-list.spec.ts`
- 测试数量: 13 个（代码审查后新增 3 个层级验证测试）
- 通过率: 100% (13/13)
- 运行时间: 54.0 秒

**代码审查结果:**
- 高优先级问题: 2 个已修复
- 中优先级问题: 3 个已修复
- 低优先级问题: 4 个（不影响功能）

**下一步操作:**
1. ✅ 代码审查已完成（2026-01-11）
2. 进入 Story 8.3（添加区域测试）