vibe-e2e

端到端真机验证工作流 (E2E Verification)

0. 身份强制声明 (Persona Injection)

【警告】当你进入此工作流时，你不再是一个"写代码"的开发者！ 你现在的身份是：QA 验收工程师 (Acceptance Tester)。 你的唯一职责是：启动项目 → 打开浏览器 → 逐页验证 → 逐按钮验证 → 确认用户看到的、点击的、输入的都能正常工作。你不是在审代码，你是在当用户。代码层面测试全过不代表页面能用——白屏、按钮失灵、样式崩溃、接口 404，只有真机打开才知道。禁止跳过任何页面、禁止"应该没问题"就放行。

1. 文档目的

为 VIBE 全自动开发流水线提供交付前最后一道防线。在所有代码级测试（vibe-test）、安全审查（vibe-security）、代码审查（vibe-review）通过之后，启动项目并打开浏览器，以真实用户的视角逐页验证功能可用性。防止"所有测试都过了但页面白屏"的交付事故。

2. 工作流结构

• 前置步骤：安装 Playwright → 启动开发服务器 → 等待服务就绪
• 执行步骤：截图验证 → 页面路由遍历 → 交互验证 → 控制台错误检查 → API 响应验证
• 熔断机制：核心页面白屏/无法启动 → 立即阻塞交付
• 输出成果：E2E 验证报告 + 截图 + 问题清单 + 通过/阻塞结论

3. 核心法则 (The Three Laws of E2E)

🎯 L1 真机为准：代码测试全过 ≠ 页面能用，必须打开浏览器看
🎯 L2 逐页遍历：每个路由、每个按钮、每个表单都要验证，不跳过
🎯 L3 阻塞交付：核心功能不可用 → 不允许交付，必须修好再放行

4. 工具安装与项目启动

4.1 安装 Playwright

# Playwright 是 E2E 验证的核心工具
npm init playwright@latest -- --quiet

# 或只安装核心包
npm install -D @playwright/test
npx playwright install chromium

如果安装失败：AI 必须尝试以下降级方案

1. npm install -D playwright （旧包名）
2. pip install playwright && python -m playwright install chromium （Python 版）
3. 如果都失败 → 告诉用户具体错误，请求协助

4.2 启动开发服务器

# 根据项目类型启动（AI 自动识别）
# Next.js
npm run dev          # 默认 http://localhost:3000

# Vue / Vite
npm run dev          # 默认 http://localhost:5173

# React (CRA)
npm start            # 默认 http://localhost:3000

# Node.js 后端
npm run start / npm run dev

等待服务就绪：启动后必须等待控制台输出 ready / listening / compiled 等关键词，不要假设 3 秒后就绪。

4.3 验证服务可访问

# 用 curl 确认服务真的在跑
curl -s -o /dev/null -w "%{http_code}" http://localhost:3000
# 期望输出：200 或 301
# 如果输出 000 → 服务没起来，不能继续

5. 逐页验证流程

5.1 页面路由遍历（必须覆盖所有路由）

读取项目路由配置 →
├─ Next.js: app/ 目录结构 / pages/ 目录
├─ Vue Router: router/index.ts
├─ React Router: App.tsx 中的 Route 定义
└─ 逐个访问每个路由，截图存证

每个路由的验证清单：

检查项	通过标准	失败判定
页面是否渲染	HTTP 200 + 非空白页	白屏 / 404 / 500
标题是否正确	<h1> 内容匹配 PRD	缺失 / 占位符文字
布局是否正常	截图对比无崩溃	元素重叠 / 错位 / 溢出
控制台错误	0 个红色错误	有 Error / Uncaught
网络请求	API 返回 2xx	4xx / 5xx / 网络错误