# Playwright MCP 续测与 E2E 指南

## 目的

本文件用于指导 AI Agent 在 Lime 中继续进行浏览器端 E2E 测试，特别适用于以下场景：

- 用户说“继续测试”“继续复现”“继续用 Playwright MCP 验证”
- 需要复用当前浏览器标签页和已有页面状态
- 需要排查浏览器模式下的 DevBridge、mock fallback、控制台报错

## 适用边界

- **优先使用 Playwright MCP** 做交互验证，不优先编写新的本地 Playwright 测试文件
- **浏览器模式默认首页不变**，从 `http://127.0.0.1:1420/` 进入
- **能走真实后端就走真实后端**；浏览器模式暂不支持或尚未桥接的能力，允许继续走 mock
- 如果只是模块级代码修改、并不需要真实页面交互，优先跑最小单测，不要强行启动整条 E2E

## AGENTS.md 最佳实践（本仓库落地版）

为避免 `AGENTS.md` 膨胀，遵循以下组织方式：

1. **根 `AGENTS.md` 只保留仓库级规则和入口索引**
2. **长流程文档放 `docs/aiprompts/`**，例如本文件
3. **只有某个子目录存在长期稳定、强作用域规则时，才新增子目录 `AGENTS.md`**
4. **临时排障记录不要写进 `AGENTS.md`**，应写入普通文档或直接在任务对话里说明

## 启动方式

### 推荐启动命令

```bash
npm run tauri:dev:headless
```

用途：
- 启动前端 dev server
- 启动 Tauri headless 调试环境
- 启动浏览器模式所需的 DevBridge
- 便于 Playwright MCP 访问 `http://127.0.0.1:1420/`

### 针对性前端校验

```bash
npm test -- src/lib/dev-bridge/safeInvoke.test.ts src/lib/tauri-mock/core.test.ts
```

适用时机：
- 修改了 `safeInvoke`
- 修改了 `src/lib/tauri-mock/`
- 修改了浏览器模式 bridge/mock 优先级

### 桥接健康检查

```bash
npm run bridge:health -- --timeout-ms 120000
```

用途：
- 等待 `http://127.0.0.1:3030/health` 就绪
- 避免 Playwright MCP 进入页面时，前端早于 DevBridge 启动而产生 `Failed to fetch` 噪音
- 首次编译较慢时，比手工反复刷新页面更稳定

### 已验证的最小冒烟路径（当前仓库）

1. 终端 A：`npm run tauri:dev:headless`
2. 终端 B：`npm run bridge:health -- --timeout-ms 120000`
3. Playwright MCP 打开 `http://127.0.0.1:1420/`
4. 等待首页从“正在加载...”进入默认首页
5. 检查 `browser_console_messages(level=error)` 应为 `0`

补充说明：
- 若首页已可用但仍有 warning，先区分是第三方库 warning 还是 bridge 缺口
- 若 `bridge:health` 已通过，但页面仍报未知命令，优先检查 `dispatcher.rs` 是否缺少该命令分发

## 继续测试的标准流程

### 1. 先确认当前 Playwright 会话是否可复用

优先顺序：

1. 调用 `browser_tabs` 查看当前标签页
2. 如果已有 `Lime` 标签页，先查看当前 URL、标题、页面状态
3. 如果页面已漂移到旧状态，直接重新导航到 `http://127.0.0.1:1420/`

建议：
- **继续测试优先复用当前标签页**，避免无意义重复建页
- **如果控制台历史噪音太多，刷新页面重新计数**

### 2. 进入页面前先检查加载状态

推荐动作：

1. 打开页面后等待“正在加载...”消失
2. 使用 `browser_snapshot` 确认首页核心元素已出现
3. 立刻检查一次 `browser_console_messages(level=error)`

通过标准：
- 首页成功加载
- 默认首页可交互
- 初始控制台 error 为 0；若非 0，需要先定位是否为 bridge 缺口

### 3. 交互时优先使用稳定定位方式

遵循 Playwright 官方最佳实践：

- 优先使用 **角色、名称、可见文本** 定位
- 优先使用 Playwright 自带等待与 web-first 断言
- **不要依赖固定 sleep** 代替状态判断
- 点击前先确认元素可见、可交互

本仓库中建议优先使用：
- `button` + 中文名称
- 页面中明确可见的标题文本
- `browser_snapshot` 返回的 ref 作为精确交互目标

## Lime 推荐 E2E 主路径

### 首页基础验证

1. 打开 `http://127.0.0.1:1420/`
2. 等待默认首页加载完成
3. 验证首页主导航可见：如“首页”“社媒内容”“设置”
4. 检查 `browser_console_messages(level=error)` 为 0

### 社媒内容工作流验证

1. 点击 `社媒内容`
2. 如果没有项目：点击 `新建项目`
3. 如果已有项目：直接选择目标项目
4. 点击 `新建文稿`
5. 选择 `新开帖子（创建新文稿）`
6. 点击 `确认生成`
7. 验证页面出现 `Theme Workbench` 或相关工作台内容
8. 再次检查 `browser_console_messages(level=error)`

### 素材页验证

1. 从社媒内容项目进入 `素材`
2. 验证素材列表可加载
3. 验证素材计数、列表项或空状态正常显示
4. 检查控制台无新增 error

## 每一步都要记录什么

执行 Playwright MCP 续测时，至少记录以下事实：

- 当前页面 URL
- 当前关键可见文本
- 是否走到了真实 bridge
- 是否触发了 mock fallback
- 控制台 error 数量
- 如失败，明确失败命令名（例如某个 invoke command）

推荐结论格式：

- 页面是否可打开
- 业务流是否走通
- 控制台是否归零
- 新暴露的命令缺口是什么
- 该缺口适合补真实 bridge 还是补 mock

## 浏览器模式常见故障与处理

### 1. `Cannot read properties of undefined (reading 'invoke')`

通常表示：
- 浏览器里加载了真实 Tauri API 包
- 没有走 web mock / HTTP bridge 链路

优先排查：
- 是否使用了浏览器模式专用启动方式
- Vite 是否正确走了 web alias
- 当前页面是否需要强制刷新以拿到最新前端代码

### 2. `[DevBridge] 未知命令`

说明：
- 前端已调用某命令
- 浏览器 bridge 分发器没有实现

处理顺序：
1. 先判断该命令是否应走真实后端
2. 如果该能力在浏览器模式下不是关键阻塞项，可加入 mock 优先集合
3. 如果该命令属于核心业务路径，优先补 `dispatcher.rs`

### 3. `Failed to fetch`

常见原因：
- DevBridge 没启动
- 3030 端口不可用
- 前端先于 bridge 就绪开始调用

处理建议：
- 确认 `tauri:dev:headless` 已启动
- 检查 bridge 健康接口
- 刷新页面后复测，排除启动时序问题

### 4. UI 已可用但控制台仍报错

说明：
- 页面可能依赖 fallback mock 继续运行
- 但仍有命令先打到了 bridge 并报 unknown command

处理建议：
- 若该命令属于浏览器模式可接受的降级能力，加入 mock 优先列表
- 若该命令属于当前主路径必须能力，补真实 bridge

## 何时补 mock，何时补真实 bridge

### 优先补真实 bridge

适用于：
- 当前主路径必须命令
- 明确已有后端实现
- 返回结构简单稳定
- 不涉及复杂流式事件或强原生依赖

### 优先补 mock

适用于：
- 浏览器模式不支持的原生能力
- 非主路径功能
- 高频噪音命令，但不影响主流程完成
- 流式/系统级能力，短期内 bridge 成本高于收益

## 结果判定标准

一次“继续测试”完成后，至少满足以下之一：

1. **主路径走通且控制台 error 归零**
2. **主路径走通，且剩余错误已被明确归类为非阻塞项**
3. **已定位新的 bridge 缺口，并给出下一步最小修复点**

## 给后续 Agent 的交接要求

如果本轮没有完全收口，请在结论中明确留下：

- 当前停留页面
- 已完成的业务步骤
- 最新暴露的命令缺口
- 推荐下一步先补 mock 还是先补 bridge
- 下一轮建议的 Playwright 复测路径