Story 3.2: 编写文件上传单元测试

Status: done

Story

作为测试开发者，我想要文件上传工具有充分的单元测试，以便确保函数的正确性和稳定性。

Acceptance Criteria

Given 文件上传工具函数已实现（packages/e2e-test-utils/src/file-upload.ts）

When 创建 tests/unit/file-upload.test.ts

Then 验收标准如下：

测试覆盖率 ≥ 80%（NFR29）
- 覆盖所有分支路径
- 覆盖所有错误处理场景
- 覆盖边界条件
测试用例包括：成功上传、文件不存在、选择器无效、超时
- 成功上传场景
- 文件不存在场景
- 选择器无效场景
- 超时配置场景
- 路径遍历攻击防护测试
- 自定义 fixtures 目录测试
使用 Vitest 运行测试
- 使用 vitest 作为测试框架
- 测试文件位于 tests/unit/file-upload.test.ts
所有测试通过
- 所有测试用例必须通过
- 无 flaky 失败

Tasks / Subtasks

[x] Task 1: 创建测试文件目录结构 (AC: #3)
- Subtask 1.1: 创建 tests/unit/ 目录（如果不存在）
- Subtask 1.2: 创建 tests/fixtures/ 测试资源目录（如果不存在）
[x] Task 2: 实现文件上传成功场景测试 (AC: #2)
- Subtask 2.1: 测试默认 fixtures 目录的文件上传
- Subtask 2.2: 测试自定义 fixtures 目录的文件上传
- Subtask 2.3: 测试子目录文件上传（如 images/sample.jpg）
- Subtask 2.4: 验证 setInputFiles API 被正确调用
[x] Task 3: 实现错误场景测试 (AC: #2)
- Subtask 3.1: 测试文件不存在错误（抛出 E2ETestError）
- Subtask 3.2: 测试选择器无效错误（抛出 E2ETestError）
- Subtask 3.3: 验证错误消息包含正确的上下文信息
[x] Task 4: 实现边界条件和安全测试 (AC: #2)
- Subtask 4.1: 测试路径遍历攻击防护（../ 路径被拒绝）
- Subtask 4.2: 测试绝对路径被拒绝
- Subtask 4.3: 测试路径遍历验证（解析后的路径在 fixtures 目录内）
- Subtask 4.4: 测试超时配置生效
[x] Task 5: 创建测试 fixtures 文件 (AC: #1, #2)
- Subtask 5.1: 创建 tests/fixtures/images/test-sample.jpg 占位文件
- Subtask 5.2: 创建 tests/fixtures/documents/test-sample.pdf 占位文件
[x] Task 6: 运行测试并验证覆盖率 (AC: #1, #4)
- Subtask 6.1: 运行 pnpm test --testNamePattern "file-upload" 验证测试通过
- Subtask 6.2: 运行 pnpm test:coverage 验证覆盖率 ≥ 80%
- Subtask 6.3: 修复覆盖率不足的分支
[x] Task 7: 添加测试文档和注释 (NFR25-NFR40)
- Subtask 7.1: 为每个测试用例添加清晰的描述
- Subtask 7.2: 添加测试场景说明注释
[x] Task 8: 代码审查修复 (2026-01-10)
- Subtask 8.1: 添加 console.debug mock 减少测试输出噪音
- Subtask 8.2: 添加边界条件测试（空文件名、空白文件名、特殊字符、超长路径）
- Subtask 8.3: 创建真实内容的测试 fixture 文件（有效的 JPEG 和 PDF）
- Subtask 8.4: 改进路径遍历安全测试覆盖

Review Follow-ups (AI Code Review - 2026-01-10)

已修复的问题

✅ MEDIUM: 测试输出污染 - 添加 vi.spyOn(console, 'debug') mock
✅ MEDIUM: 缺少边界条件测试 - 添加了空文件名、空白、特殊字符、超长路径测试
✅ HIGH: 测试使用空字节文件 - 创建了真实有效的 JPEG (22 bytes) 和 PDF (230 bytes) 文件
✅ MEDIUM: Git 文件未提交 - 所有文件已提交

已知限制

⚠️ file-upload.ts:142-147 路径遍历验证分支未覆盖
- 这段代码是防御性安全检查，验证解析后的路径在 fixtures 目录内
- 未覆盖原因：该分支需要真实文件系统操作（如 symbolic links）才能触发
- 建议：在 Story 3.3 E2E 集成测试中验证此安全机制
- 当前覆盖率：91.66% 语句, 90% 分支（仍超过 80% 要求）

最终测试结果

测试数量: 37 个测试用例（36 passed, 1 skipped - Windows 特定）
覆盖率: 91.66% 语句, 90% 分支, 100% 函数, 91.66% 行数
所有验收标准: ✅ 通过

Dev Notes

Epic 3 背景与目标

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

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

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

当前进度：

Story 3.1: ✅ 已完成 - uploadFileToField() 函数已实现
Story 3.2: 🔄 本 Story - 编写单元测试

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

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

单元测试无法发现真实 DOM 问题
- Epic 2 的 Select 工具单元测试覆盖率 93.65%，仍然无法发现 DOM 结构问题
- 原因：单元测试使用模拟 DOM，不是真实的 Radix UI 组件
- 教训：不能仅依赖单元测试验证工具正确性
真实 E2E 测试不可替代
- DOM 结构假设必须基于真实组件验证
- 选择器策略必须在真实浏览器中测试
- 集成测试是必需的，不是可选项
本 Story 的定位
- 单元测试用于验证基本逻辑（路径解析、错误处理、边界条件）
- 不能替代 Story 3.3 的真实 E2E 集成测试
- 重点测试：resolveFixturePath() 函数逻辑、错误抛出、安全防护

技术规范

被测函数分析

uploadFileToField() 函数结构：

// packages/e2e-test-utils/src/file-upload.ts

export async function uploadFileToField(
  page: Page,
  selector: string,
  fileName: string,
  options?: FileUploadOptions
): Promise<void>

// 内部辅助函数（需要重点测试）
function resolveFixturePath(fileName: string, fixturesDir: string): string

关键测试点：

resolveFixturePath() 函数逻辑 - 核心测试重点
- 拒绝绝对路径
- 拒绝包含 .. 的路径
- 验证解析后的路径在 fixtures 目录内（防止路径遍历攻击）
- 正确解析相对路径
错误处理
- 文件不存在时抛出 E2ETestError
- 选择器无效时抛出 E2ETestError
- 错误消息包含正确的上下文信息
Playwright API 交互 - 单元测试中的模拟
- page.locator(selector) 返回 Locator 对象
- locator.setInputFiles(filePath, { timeout }) 被调用
- page.waitForTimeout(200) 在 waitForUpload: true 时被调用

Vitest 配置

配置文件： packages/e2e-test-utils/vitest.config.ts

{
  test: {
    dir: './tests/unit',          // 单元测试目录
    environment: 'node',          // Node.js 环境
    testTimeout: 10000,           // 10秒超时
    coverage: {
      statements: 80,             // 语句覆盖率目标
      branches: 80,               // 分支覆盖率目标
      functions: 80,              // 函数覆盖率目标
      lines: 80                   // 行覆盖率目标
    }
  }
}

测试 Mock 策略

Mock Playwright Page 对象：

import { describe, it, expect, vi, beforeEach } from 'vitest';
import { uploadFileToField } from '../src/file-upload';
import { E2ETestError } from '../src/errors';

// Mock Page 和 Locator
const mockLocator = {
  setInputFiles: vi.fn().mockResolvedValue(undefined)
};

const mockPage = {
  locator: vi.fn().mockReturnValue(mockLocator),
  waitForTimeout: vi.fn().mockResolvedValue(undefined)
};

测试用例设计

场景 1: 成功上传（默认 fixtures 目录）

测试目标： 验证基本文件上传流程

it('应该成功上传文件（使用默认 fixtures 目录）', async () => {
  // Arrange
  const fileName = 'test-sample.jpg';
  const selector = 'photo-upload';

  // Act
  await uploadFileToField(mockPage, selector, fileName);

  // Assert
  expect(mockPage.locator).toHaveBeenCalledWith(selector);
  expect(mockLocator.setInputFiles).toHaveBeenCalledWith(
    expect.stringContaining(fileName),
    { timeout: 5000 }
  );
});

场景 2: 成功上传（自定义 fixtures 目录）

测试目标： 验证自定义 fixtures 目录配置

it('应该使用自定义 fixtures 目录上传文件', async () => {
  // Arrange
  const customDir = 'custom/fixtures';
  const fileName = 'test-sample.jpg';

  // Act
  await uploadFileToField(mockPage, 'photo-upload', fileName, {
    fixturesDir: customDir
  });

  // Assert
  expect(mockLocator.setInputFiles).toHaveBeenCalledWith(
    expect.stringContaining(customDir),
    expect.anything()
  );
});

场景 3: 文件不存在错误

测试目标： 验证文件不存在时抛出正确的错误

it('应该在文件不存在时抛出 E2ETestError', async () => {
  // Arrange
  const nonExistentFile = 'non-existent-file.jpg';

  // Act & Assert
  await expect(
    uploadFileToField(mockPage, 'photo-upload', nonExistentFile)
  ).rejects.toThrow(E2ETestError);
});

场景 4: 选择器无效错误

测试目标： 验证选择器无效时抛出正确的错误

it('应该在选择器无效时抛出 E2ETestError', async () => {
  // Arrange
  mockLocator.setInputFiles.mockRejectedValue(
    new Error('Element not found')
  );

  // Act & Assert
  await expect(
    uploadFileToField(mockPage, 'invalid-selector', 'test.jpg')
  ).rejects.toThrow(E2ETestError);
});

场景 5: 路径遍历攻击防护

测试目标： 验证安全防护机制

it('应该拒绝包含 ".." 的路径（路径遍历攻击防护）', async () => {
  // Act & Assert
  await expect(
    uploadFileToField(mockPage, 'photo-upload', '../../../etc/passwd')
  ).rejects.toThrow(E2ETestError);
});

it('应该拒绝绝对路径', async () => {
  // Act & Assert
  await expect(
    uploadFileToField(mockPage, 'photo-upload', '/etc/passwd')
  ).rejects.toThrow(E2ETestError);
});

场景 6: 超时配置

测试目标： 验证自定义超时生效

it('应该使用自定义超时配置', async () => {
  // Arrange
  const customTimeout = 10000;

  // Act
  await uploadFileToField(mockPage, 'photo-upload', 'test.jpg', {
    timeout: customTimeout
  });

  // Assert
  expect(mockLocator.setInputFiles).toHaveBeenCalledWith(
    expect.anything(),
    { timeout: customTimeout }
  );
});

项目结构说明

包结构：

packages/e2e-test-utils/
├── src/
│   ├── file-upload.ts         # 被测函数
│   ├── types.ts               # FileUploadOptions 类型
│   ├── errors.ts              # E2ETestError 类
│   └── constants.ts           # DEFAULT_TIMEOUTS 常量
├── tests/
│   ├── unit/
│   │   └── file-upload.test.ts  # 本 Story 创建的测试文件
│   └── fixtures/              # 测试资源目录
│       ├── images/
│       │   └── test-sample.jpg
│       └── documents/
│           └── test-sample.pdf
├── vitest.config.ts           # Vitest 配置
└── package.json

测试 fixtures 目录位置：

目录	用途
`packages/e2e-test-utils/tests/fixtures/`	单元测试使用的 fixtures
`web/tests/fixtures/`	默认配置的 fixtures（用于 E2E 测试）

运行测试命令

运行单元测试：

# 在 packages/e2e-test-utils 目录下
pnpm test --testNamePattern "file-upload"

# 从项目根目录
pnpm --filter @d8d/e2e-test-utils test --testNamePattern "file-upload"

运行覆盖率测试：

pnpm test:coverage

参考文档

架构文档：

_bmad-output/planning-artifacts/architecture.md - 测试策略、单元测试规范

E2E 测试标准：

docs/standards/testing-standards.md - 单元测试编写规范

Epic 3 完整需求：

_bmad-output/planning-artifacts/epics.md - Epic 3 和 Story 3.2 详细需求

Epic 2 回顾（关键经验）：

_bmad-output/implementation-artifacts/epic-2-retrospective.md - 单元测试局限性

TypeScript + Playwright 陷阱：

architecture.md 第 533-657 行 - DOM 结构假设必须验证

已实现的源文件参考

被测文件：

[Source: packages/e2e-test-utils/src/file-upload.ts]

相关类型：

[Source: packages/e2e-test-utils/src/types.ts] - FileUploadOptions 接口

错误处理：

[Source: packages/e2e-test-utils/src/errors.ts] - E2ETestError 类

常量定义：

[Source: packages/e2e-test-utils/src/constants.ts] - DEFAULT_TIMEOUTS

Project Structure Notes

Monorepo 结构对齐：

包位于 packages/e2e-test-utils/
使用 pnpm workspace 协议
测试框架：Vitest（单元测试）

文件组织：

测试文件位于 tests/unit/ 目录
测试资源位于 tests/fixtures/ 目录
使用 .test.ts 后缀命名

References

源文档引用：

[Source: _bmad-output/planning-artifacts/epics.md#Epic-3-Story-3.2]
[Source: _bmad-output/planning-artifacts/architecture.md#Testing-Configuration]
[Source: _bmad-output/implementation-artifacts/3-1-file-upload-tool.md] - Story 3.1 实现经验

Epic 2 经验教训：

[Source: _bmad-output/implementation-artifacts/epic-2-retrospective.md] - 单元测试局限性分析

Dev Agent Record

Agent Model Used

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

Debug Log References

Completion Notes List

实现概述

创建了 tests/unit/file-upload.test.ts 单元测试文件
最终测试结果：37 个测试用例（36 passed, 1 skipped - Windows 特定）
测试覆盖率：91.66% 语句, 90% 分支, 100% 函数, 91.66% 行数（超过 80% 要求）

测试场景覆盖

成功上传场景 (Task 2)
- 默认 fixtures 目录上传
- 自定义 fixtures 目录上传
- 子目录文件上传
- setInputFiles API 调用验证
错误场景 (Task 3)
- 文件不存在错误
- 选择器无效错误
- 错误消息上下文验证
边界条件和安全 (Task 4)
- 路径遍历攻击防护 (../ 路径拒绝)
- 绝对路径拒绝
- 路径遍历验证
- 超时配置生效
边界条件和额外安全 (Task 4+)
- 空文件名和空白文件名处理
- 特殊字符文件名处理
- 超长路径处理
- 复杂路径遍历尝试拒绝

平台兼容性处理

Windows 绝对路径测试使用 skip: process.platform !== 'win32' 跳过
避免在 Linux 系统上测试 Windows 特定路径格式

Epic 2 经验应用

单元测试重点验证 resolveFixturePath() 函数逻辑
使用 vi.fn() 模拟 Playwright Page 对象
验证 E2ETestError 错误上下文完整性
注意：单元测试无法替代 Story 3.3 的真实 E2E 集成测试

File List

新增文件

packages/e2e-test-utils/tests/unit/file-upload.test.ts - 文件上传单元测试（37 个测试用例）
packages/e2e-test-utils/tests/fixtures/documents/test-sample.pdf - 有效 PDF 测试文件（230 bytes）
packages/e2e-test-utils/tests/fixtures/images/test-sample.jpg - 有效 JPEG 测试文件（22 bytes）

3-2-upload-unit-tests.md 15 KB Cronologia Originale