ContextQMD
Back to Prompt Optimizer

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

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

2.10.29.6 KB
Original Source

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

目标

设计并实施一个全面可靠的自动化测试方案，解决当前 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）