# Story 3.3: 在 E2E 测试中验证文件上传工具

Status: ready-for-dev

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

## Story

作为 E2E 测试开发者，
我想要在真实的 E2E 测试中使用 `uploadFileToField()` 工具函数，
以便验证文件上传工具在实际场景中的可用性和稳定性。

## Acceptance Criteria

**Given** Story 3.1 已实现 `uploadFileToField()` 函数（含 UI 组件 testId 支持）
**Given** Story 3.2 已完成单元测试（覆盖率 91.66%）
**Given** PhotoUploadField 组件已添加 testId prop（`testId={"photo-upload-${index}"}`）

**When** 在 `web/tests/e2e/` 中创建或更新测试文件

**Then** 验收标准如下：

1. **创建独立的文件上传 E2E 测试文件**
   - 创建 `web/tests/e2e/specs/admin/file-upload-validation.spec.ts`
   - 测试文件验证 `uploadFileToField()` 在真实场景中的可用性
   - 测试使用真实 MinIO 文件上传流程（非模拟）

2. **测试场景包括**
   - 基本文件上传：使用 testId 选择器上传照片
   - 多文件上传：连续上传多张照片
   - 不同文件类型：上传不同格式的图片文件
   - 错误处理：文件不存在、选择器无效等场景

3. **使用真实 fixtures 文件**
   - 使用 `web/tests/fixtures/images/` 中的真实图片文件
   - 验证文件路径解析正确（相对于 web/tests/fixtures）
   - 验证文件上传后能正确显示预览

4. **测试在真实浏览器中运行**
   - 使用 Playwright 运行完整测试
   - 测试通过率 100%
   - 无超时或失败

5. **收集反馈并记录问题**
   - 记录测试过程中发现的任何问题
   - 验证工具的易用性和错误提示
   - 确认单元测试未覆盖的问题

## Tasks / Subtasks

- [ ] **Task 1: 创建文件上传 E2E 测试文件** (AC: #1, #2)
  - [ ] Subtask 1.1: 创建 `file-upload-validation.spec.ts` 测试文件
  - [ ] Subtask 1.2: 导入 `uploadFileToField` 函数
  - [ ] Subtask 1.3: 创建测试套件和 fixture 设置

- [ ] **Task 2: 实现基本文件上传测试** (AC: #2, #3)
  - [ ] Subtask 2.1: 测试单张照片上传（身份证照片）
  - [ ] Subtask 2.2: 使用 testId 选择器 `[data-testid="photo-upload-0"]`
  - [ ] Subtask 2.3: 验证上传成功后显示预览

- [ ] **Task 3: 实现多文件上传测试** (AC: #2)
  - [ ] Subtask 3.1: 测试连续上传多张照片
  - [ ] Subtask 3.2: 使用不同的 testId (`photo-upload-1`, `photo-upload-2`)
  - [ ] Subtask 3.3: 验证每张照片上传成功

- [ ] **Task 4: 实现 E2E 集成测试（完整表单场景）** (AC: #2, #4)
  - [ ] Subtask 4.1: 测试完整的残疾人创建流程（含照片上传）
  - [ ] Subtask 4.2: 验证表单提交成功
  - [ ] Subtask 4.3: 验证数据保存正确

- [ ] **Task 5: 运行测试并收集结果** (AC: #4, #5)
  - [ ] Subtask 5.1: 运行 E2E 测试：`pnpm test:e2e:chromium file-upload-validation`
  - [ ] Subtask 5.2: 记录测试结果和任何错误
  - [ ] Subtask 5.3: 保存失败截图（如果有）

- [ ] **Task 6: 更新 disability-person.page.ts** (可选 - AC: #4)
  - [ ] Subtask 6.1: 更新 `uploadPhoto()` 方法使用 `uploadFileToField()`
  - [ ] Subtask 6.2: 简化 DOM 操作，使用 testId 选择器
  - [ ] Subtask 6.3: 删除复杂的 XPath 查询和模拟文件逻辑

- [ ] **Task 7: 编写测试报告** (AC: #5)
  - [ ] Subtask 7.1: 记录测试覆盖率（哪些场景已验证）
  - [ ] Subtask 7.2: 记录发现的问题和修复建议
  - [ ] Subtask 7.3: 确认单元测试未覆盖的场景

## Dev Notes

### Epic 3 背景与目标

**Epic 3: 文件上传工具开发与验证**

遵循 Epic 2 的成功模式，开发文件上传工具并在真实 E2E 测试中验证，解决当前测试超时阻塞问题。

**模式：** 工具开发 → 真实 E2E 测试验证 → 问题修复 → 稳定性验证

**当前进度：**
- Story 3.1: ✅ 已完成 - `uploadFileToField()` 函数已实现（含 UI 组件 testId 支持）
- Story 3.2: ✅ 已完成 - 单元测试（覆盖率 91.66%）
- Story 3.3: 🔄 本 Story - 在真实 E2E 测试中验证文件上传工具

### ⚠️ Epic 2 关键经验应用（必须阅读）

**单元测试的局限性（来自 Epic 2 回顾）：**

1. **单元测试无法发现真实 DOM 问题**
   - Epic 2 的 Select 工具单元测试覆盖率 93.65%，仍然无法发现 DOM 结构问题
   - 原因：单元测试使用模拟 DOM，不是真实的 Radix UI 组件
   - **教训：** 必须在真实 E2E 环境中验证工具

2. **真实 E2E 测试不可替代**
   - DOM 结构假设必须基于真实组件验证
   - 选择器策略必须在真实浏览器中测试
   - 集成测试是必需的，不是可选项

3. **本 Story 的定位**
   - 单元测试（Story 3.2）验证了基本逻辑和错误处理
   - **本 Story** 验证与真实 DOM 的交互和完整文件上传流程
   - 重点测试：真实文件上传、浏览器行为、MinIO 集成

### 技术规范

#### 当前 E2E 测试文件上传实现分析

**disability-person.page.ts 中的 uploadPhoto() 方法（第 176-205 行）：**

```typescript
async uploadPhoto(photoType: string, fileName: string) {
  // ❌ 问题 1: 使用复杂的 XPath 查找
  const photoSection = this.page.locator('text=' + photoType).first();
  await photoSection.scrollIntoViewIfNeeded();

  const uploadButton = photoSection.locator('xpath=ancestor::div[contains(@class, "space-y-")]').first()
    .getByRole('button', { name: /上传/ }).first();

  // ❌ 问题 2: 使用 evaluateHandle 查找隐藏的 file input
  const fileInput = await uploadButton.evaluateHandle((el: any) => {
    const input = el.querySelector('input[type="file"]');
    return input;
  });

  // ❌ 问题 3: 创建假图片文件
  const file = {
    name: fileName,
    mimeType: 'image/jpeg',
    buffer: Buffer.from('fake image content')
  };

  await fileInput.uploadFile(file as any);
}
```

**问题总结：**
1. XPath 查询脆弱且难以维护
2. `evaluateHandle` 增加复杂度
3. 假文件内容无法测试真实图片上传流程

#### 新的 uploadFileToField() 工具函数

**函数签名（已实现）：**
```typescript
import { uploadFileToField } from '@d8d/e2e-test-utils';

await uploadFileToField(
  page,                          // Playwright Page 对象
  '[data-testid="photo-upload-0"]', // 选择器
  'sample-id-card.jpg',          // 文件名（相对于 web/tests/fixtures）
  { timeout: 5000 }              // 可选配置
);
```

**关键特性：**
1. ✅ 使用 `page.locator().setInputFiles()` API（Playwright 标准）
2. ✅ 自动解析 fixtures 路径（默认 `web/tests/fixtures`）
3. ✅ 完整的错误处理（文件不存在、选择器无效）
4. ✅ 支持真实文件上传

#### PhotoUploadField testId 架构

**组件结构（PhotoUploadField.tsx 第 172 行）：**
```tsx
<FileSelector
  value={photo.fileId}
  onChange={(fileId) => handleFileIdChange(index, fileId)}
  testId={`photo-upload-${index}`}  // ← 关键：生成唯一 testId
/>
```

**FileSelector → MinioUploader 传递链：**
```
PhotoUploadField (testId={"photo-upload-${index}"})
    ↓
FileSelector (testId prop)
    ↓
MinioUploader (添加隐藏的 <input type="file" data-testid={testId}>)
```

**测试使用方式：**
```typescript
// 上传第 1 张照片（身份证照片）
await uploadFileToField(page, '[data-testid="photo-upload-0"]', 'sample-id-card.jpg');

// 上传第 2 张照片（残疾证照片）
await uploadFileToField(page, '[data-testid="photo-upload-1"]', 'sample-disability-card.jpg');
```

### 测试场景设计

#### 场景 1: 基本文件上传验证

**测试目标：** 验证 `uploadFileToField()` 能成功上传单个文件

```typescript
test('应该成功上传单张照片', async ({ disabilityPersonPage, page }) => {
  const timestamp = Date.now();

  // 1. 打开对话框并填写基本信息
  await disabilityPersonPage.openCreateDialog();
  await disabilityPersonPage.fillBasicForm({
    name: `文件上传测试_${timestamp}`,
    gender: '男',
    idCard: '420101199001011234',
    disabilityId: '51100119900101',
    disabilityType: '视力残疾',
    disabilityLevel: '一级',
    phone: '13800138000',
    idAddress: '湖北省武汉市测试街道1号',
    province: '湖北省',
    city: '武汉市'
  });

  // 2. 滚动到照片区域并添加一张照片
  await disabilityPersonPage.scrollToSection('照片');
  await page.getByTestId('add-photo-button').click();

  // 3. 使用 uploadFileToField 上传文件
  await uploadFileToField(page, '[data-testid="photo-upload-0"]', 'sample-id-card.jpg');

  // 4. 验证上传成功（检查预览或文件名显示）
  const preview = page.locator('[data-testid="photo-upload-0"]').locator('img');
  await expect(preview).toBeVisible({ timeout: 5000 });
});
```

#### 场景 2: 多文件上传验证

**测试目标：** 验证连续上传多张文件

```typescript
test('应该成功上传多张照片', async ({ disabilityPersonPage, page }) => {
  const timestamp = Date.now();

  // 1. 打开对话框并填写基本信息
  await disabilityPersonPage.openCreateDialog();
  await disabilityPersonPage.fillBasicForm({...});

  // 2. 滚动到照片区域
  await disabilityPersonPage.scrollToSection('照片');

  // 3. 添加三张照片
  await page.getByTestId('add-photo-button').click();
  await uploadFileToField(page, '[data-testid="photo-upload-0"]', 'sample-id-card.jpg');

  await page.getByTestId('add-photo-button').click();
  await uploadFileToField(page, '[data-testid="photo-upload-1"]', 'sample-disability-card.jpg');

  await page.getByTestId('add-photo-button').click();
  await uploadFileToField(page, '[data-testid="photo-upload-2"]', 'sample-id-card.jpg');

  // 4. 验证所有照片都上传成功
  const previews = page.locator('[data-testid^="photo-upload-"]').locator('img');
  await expect(previews).toHaveCount(3);
});
```

#### 场景 3: 完整表单提交验证

**测试目标：** 验证文件上传后的表单能成功提交

```typescript
test('应该成功提交包含照片的表单', async ({ disabilityPersonPage, page }) => {
  const timestamp = Date.now();

  // 1. 打开对话框并填写基本信息
  await disabilityPersonPage.openCreateDialog();
  await disabilityPersonPage.fillBasicForm({...});

  // 2. 上传照片
  await disabilityPersonPage.scrollToSection('照片');
  await page.getByTestId('add-photo-button').click();
  await uploadFileToField(page, '[data-testid="photo-upload-0"]', 'sample-id-card.jpg');

  // 3. 提交表单
  const result = await disabilityPersonPage.submitForm();

  // 4. 验证提交成功
  expect(result.hasSuccess).toBe(true);
  expect(result.hasError).toBe(false);

  // 5. 验证数据保存
  await disabilityPersonPage.waitForDialogClosed();
  await page.reload();
  await disabilityPersonPage.goto();
  await disabilityPersonPage.searchByName(`文件上传测试_${timestamp}`);

  const personExists = await disabilityPersonPage.personExists(`文件上传测试_${timestamp}`);
  expect(personExists).toBe(true);
});
```

### 项目结构说明

**测试文件位置：**
```
web/tests/
├── e2e/
│   ├── specs/
│   │   └── admin/
│   │       ├── file-upload-validation.spec.ts  # 本 Story 创建
│   │       └── disability-person-complete.spec.ts  # 现有测试
│   ├── fixtures/
│   │   └── images/
│   │       ├── sample-id-card.jpg           # 已存在
│   │       └── sample-disability-card.jpg   # 已存在
│   └── pages/
│       └── admin/
│           └── disability-person.page.ts    # 现有 Page Object
```

**包依赖：**
```typescript
// web/tests/e2e/specs/admin/file-upload-validation.spec.ts
import { uploadFileToField } from '@d8d/e2e-test-utils';
```

### 运行测试命令

**运行本 Story 的测试：**
```bash
# 从项目根目录
cd web && pnpm test:e2e:chromium file-upload-validation

# 快速失败模式（推荐调试时使用）
timeout 60 pnpm test:e2e:chromium file-upload-validation
```

**运行完整的残疾人管理测试（验证集成）：**
```bash
cd web && pnpm test:e2e:chromium disability-person-complete
```

### 参考文档

**架构文档：**
- `_bmad-output/planning-artifacts/architecture.md` - E2E 测试标准、三层测试策略

**E2E 测试标准：**
- `docs/standards/e2e-radix-testing.md` - 文件上传测试标准

**Epic 3 完整需求：**
- 相关故事文件已在 `_bmad-output/implementation-artifacts/` 中

**Epic 2 回顾（关键经验）：**
- `_bmad-output/implementation-artifacts/epic-2-retrospective.md` - 真实 E2E 测试的价值

**TypeScript + Playwright 陷阱：**
- `architecture.md` 第 533-657 行 - DOM 结构假设必须验证

**已实现的源文件参考：**
- [Source: packages/e2e-test-utils/src/file-upload.ts] - uploadFileToField 函数实现
- [Source: allin-packages/disability-person-management-ui/src/components/PhotoUploadField.tsx] - testId 架构
- [Source: web/tests/e2e/pages/admin/disability-person.page.ts] - 当前 uploadPhoto 方法

### Project Structure Notes

**Monorepo 结构对齐：**
- E2E 测试在 `web/tests/e2e/` 目录
- 使用 `@d8d/e2e-test-utils` workspace 包
- 测试 fixtures 位于 `web/tests/fixtures/`

**文件组织：**
- 测试文件按功能组织在 `specs/admin/` 目录
- 使用 `.spec.ts` 后缀命名（Playwright 约定）
- Page Objects 位于 `pages/admin/` 目录

### References

**源文档引用：**
- [Source: _bmad-output/implementation-artifacts/3-1-file-upload-tool.md] - 文件上传工具实现
- [Source: _bmad-output/implementation-artifacts/3-2-upload-unit-tests.md] - 单元测试结果
- [Source: _bmad-output/implementation-artifacts/epic-2-retrospective.md] - E2E 验证经验

**现有测试参考：**
- [Source: web/tests/e2e/specs/admin/disability-person-complete.spec.ts] - 完整流程测试
- [Source: web/tests/e2e/pages/admin/disability-person.page.ts] - Page Object 实现

## Dev Agent Record

### Agent Model Used

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

### Debug Log References

### Completion Notes List

_本 Story 正在开发中，完成时将记录：_
- 创建的测试文件和测试用例数量
- 测试执行结果（通过/失败）
- 发现的问题和修复记录

### File List

_本 Story 预计创建/修改的文件：_

**新增文件：**
- `web/tests/e2e/specs/admin/file-upload-validation.spec.ts` - 文件上传 E2E 验证测试

**可能修改的文件：**
- `web/tests/e2e/pages/admin/disability-person.page.ts` - 更新 uploadPhoto() 方法使用 uploadFileToField()

---

**Story 创建日期:** 2026-01-10
**Story 状态:** ready-for-dev