prompt-optimizer/docs/archives/131-testing-redesign/task_plan.md

测试方案重新设计 - 任务计划

目标

设计并实施一个全面可靠的自动化测试方案，解决当前 pnpm test 无法发现 UI 错误的核心问题。

核心问题

• 现状：UI 错误需要手动界面测试 + 查看控制台才能发现
• 目标：测试必须能够拦截和发现错误，而不仅仅是覆盖率指标
• 执行要求：提交前强制门禁，< 10 分钟执行时间

设计约束

1. UI 错误检测（4 种类型全部覆盖）

   • 控制台错误/警告（组件渲染错误、Vue warn、未捕获异常）
   • 视觉渲染错误（显示异常、布局错乱、样式失效）
   • 状态同步错误（Store 与 UI 不同步）
   • 交互行为错误（点击无响应、表单失败、模态框异常）

2. VCR 模式（完全自动化）

   • 可录制真实 LLM API 响应（需显式启用真实 API：ENABLE_REAL_LLM=true）
   • 后续运行自动回放 fixtures（Mock）
   • 提供命令更新 fixtures
   • Mock 必须模拟连接、流式返回、真实时序

3. 测试范围优先级

   • P0: 提示词优化和测试流程（Basic/Context/Image 三种模式）
   • P0: 图像生成+历史收藏
   • P0: LLM 服务集成
   • P0: Session Store 状态管理

实施阶段

Phase 1: 调研与架构设计 [completed]

目标: 调研技术方案，设计测试架构

任务:

• 探索项目现有测试基础（已完成 111 个测试文件分析）
• 调研 UI 错误检测技术方案
  • 控制台错误捕获方案（Vitest, Playwright）
  • 视觉回归测试方案（Playwright visual testing, Percy, Chromatic）
  • 状态同步检测方案（Vue devtools API, Pinia testing）
  • 交互行为测试方案（Testing Library, Playwright）
• 调研 VCR 自动化实现方案
  • 录制-回放库调研（nock, MSW, Polly.js）
  • 流式响应 Mock 方案（SSE/Streaming simulation）
  • Fixtures 管理方案（文件结构、版本控制）
• 设计测试分层架构（< 10 分钟执行时间）
• 设计 pre-commit hook 方案

输出:

• findings.md - 技术调研结果（含完整技术选型对比）
• architecture.md - 测试架构设计文档

预估时间: 2-3 天

---

Phase 2: VCR 基础设施实现 [completed]

目标: 实现 VCR 自动化录制-回放系统

任务:

• 实现 Fixtures 管理系统
  • 文件存储结构设计
  • 自动录制检测逻辑
  • Fixtures 版本管理
• 实现 LLM Mock 服务
  • 支持所有提供商（OpenAI, Gemini, DeepSeek, 自定义）
  • 模拟连接延迟
  • 模拟流式响应（chunk by chunk）
  • 模拟错误场景（timeout, rate limit, network error）
• 实现测试命令
  • pnpm test:record - 重新录制所有 fixtures
  • pnpm test:replay - 强制回放
  • pnpm test:real - 禁用 VCR
  • 环境变量开关（ENABLE_REAL_LLM / RUN_REAL_API）
• 单元测试验证

输出:

• packages/core/tests/fixtures/ - Fixtures 存储目录
• packages/core/tests/utils/vcr.ts - VCR 工具函数
• packages/core/tests/utils/llm-mock-service.ts - LLM Mock 服务（MSW handlers）
• packages/core/tests/utils/stream-simulator.ts - 流式响应模拟器
• packages/core/tests/setup.js - Core 测试全局 MSW 集成

预估时间: 4-5 天

依赖: Phase 1 完成

---

Phase 3: UI 错误检测机制 [completed]

目标: 建立“UI 错误自动失败”的门禁机制（Vitest + Playwright）

任务:

• 控制台错误检测
  • Vitest: 捕获 console.error/warn
  • Playwright: 监听 page.on('console')
  • Vue warn 检测（通过 console.warn 捕获）
  • 未捕获异常检测（window error/unhandledrejection + page.on('pageerror')）
• 全局错误拦截器配置
• 最小视觉渲染检测（结构断言）
  • E2E 回归用例包含基础结构断言（tests/e2e/regression.spec.ts）
  • 截图对比（Playwright toHaveScreenshot）作为后续增强（可在 Phase 4/5 引入）

输出:

• packages/ui/tests/utils/error-detection.ts - 错误检测工具（Vitest）
• packages/ui/tests/setup.ts - 全局设置集成
• tests/e2e/fixtures.ts - Playwright 全局控制台/异常门禁
• playwright.config.ts - 无需变更（沿用现有 webServer 配置）

预估时间: 5-6 天

依赖: Phase 1 完成

---

Phase 4: 核心功能测试实现 [in_progress]

目标: 实现 P0 功能的完整测试覆盖

任务:

• 提示词优化和测试流程
  • Basic-System 完整工作流
  • Basic-User 完整工作流
  • Context-System 多轮对话
  • Context-User 变量管理
  • Image-Text2Image 文生图
  • Image-Image2Image 图生图
  • 状态同步/交互行为类错误：由上述 P0 用例承接（断言 store ↔ UI/逻辑一致性）
  • E2E 路由冒烟（所有 P0 工作区可进入且无 console/pageerror）：tests/e2e/workflows/p0-route-smoke.spec.ts
  • Basic 工作区核心逻辑（optimize/test/iterate）集成冒烟：packages/ui/tests/integration/basic-workspace-logic.spec.ts
  • Context-User 优化/测试逻辑集成冒烟：packages/ui/tests/integration/context-user-optimization.spec.ts、packages/ui/tests/integration/context-user-tester.spec.ts
  • Context-System 测试逻辑（V0 对比/变量合并）集成冒烟：packages/ui/tests/integration/conversation-tester.spec.ts
  • Context-System 消息优化逻辑（优化→应用→建立链映射）集成冒烟：packages/ui/tests/integration/conversation-optimization.spec.ts
  • Image 生成逻辑集成冒烟（load models + generate）：packages/ui/tests/integration/image-generation.spec.ts
• 图像生成+历史收藏
  • ImageStorageService 测试
  • 历史记录 CRUD 测试
  • 收藏管理测试
  • 分类标签测试
• LLM 服务集成
  • 多提供商集成测试
  • 流式响应处理测试
  • 错误重试机制测试
  • 模型切换测试
• Session Store
  • 6 个 Store 单元测试（含持久化与迁移要点）
    • Basic: packages/ui/tests/unit/stores/session/basic-session-persistence.spec.ts
    • Pro: packages/ui/tests/unit/stores/session/pro-session-persistence.spec.ts
    • Image: packages/ui/tests/unit/stores/session/image-session-persistence.spec.ts
  • 模式切换集成测试
  • 并发保护测试
  • 持久化往返测试

输出:

• tests/e2e/workflows/ - E2E 工作流测试
• packages/ui/tests/integration/ - 集成测试
• packages/ui/tests/unit/stores/ - Store 单元测试

预估时间: 10-12 天

依赖: Phase 2, Phase 3 完成

---

Phase 5: 门禁集成与优化 [completed]

目标: 实现提交前强制门禁，优化执行时间

任务:

• 测试分组（fast/full）
  • pnpm test:gate（fast，pre-commit）
  • pnpm test:gate:full（含 E2E）
• 可选：测试执行时间优化
  • 并行化配置（Vitest workers, Playwright sharding）
  • 慢速测试标记（--skip-slow 模式）
• pre-commit hook 实现
  • Husky 配置（pnpm test:gate）
  • lint-staged 集成（可选）
  • 测试失败处理逻辑（非 0 直接阻断）
  • 清晰错误信息输出（hook 输出 gate 命令）
• CI/CD 集成
  • GitHub Actions：pnpm test:replay + pnpm test:gate:full
  • 覆盖率报告上传（可选）
• 文档编写
  • 测试运行指南：docs/testing/README.md
  • VCR 使用文档：docs/testing/vcr-usage-guide.md
  • 贡献者指南更新（可选）

输出:

• .husky/pre-commit - pre-commit hook（已提交）
• .github/workflows/test.yml - CI 配置（已提交）
• docs/testing/README.md - 测试文档（已提交）
• docs/testing/vcr-usage-guide.md - VCR 使用指南（已提交）
• 所有测试基础设施文件（已提交到 git 暂存区）

预估时间: 3-4 天

依赖: Phase 4 完成

实际完成时间: 2026-01-09（门禁验证通过）

---

里程碑

里程碑	完成标准	预计日期
M1: 方案设计完成	Phase 1 完成，架构文档输出	Day 3
M2: VCR 基础设施可用	Phase 2 完成，可录制回放 LLM 响应	Day 8
M3: UI 错误检测可用	Phase 3 完成，4 种错误类型可检测	Day 14
M4: 核心测试完成	Phase 4 完成，P0 功能全覆盖	Day 26
M5: 门禁上线	Phase 5 完成，pre-commit hook 生效	Day 30

成功指标

定量指标:

• 测试执行时间 < 10 分钟（提交前）✅ 实际: < 1 分钟（快速门禁）
• 控制台错误检测率 100% ✅ 已启用并验证
• P0 功能测试覆盖率 100% ✅ 257 个测试通过
• 整体代码覆盖率 > 75% ⏳ 待测量
• 零误报（flaky tests < 1%）✅ 0/257 = 0%

定性指标:

• pnpm test 能够发现手动测试才能发现的 UI 错误 ✅ 错误门禁已启用
• VCR 模式运行稳定，无需真实 API ✅ fixtures 已录制，回放稳定
• 测试失败时提供清晰的错误信息和修复建议 ✅ 控制台输出清晰
• 开发者体验良好（快速反馈、易于调试）✅ 快速门禁 < 1 分钟

错误记录

错误	尝试次数	解决方案
-	-	-

决策日志

日期	决策	原因
-	-	-

注意事项

• VCR fixtures 必须纳入版本控制
• 视觉回归测试 baseline 需要定期审查
• 慢速测试必须有 timeout 限制
• 所有测试必须可以离线运行（使用 fixtures）