web-e2e git:20260805.5563910A

Immutable. This exact content never changes and is served at /api/v1/blob/9d9de18555eab353.

---
name: web-e2e
description: "维护和复用 Web 应用的 Playwright E2E 实战经验。用于把需求与真实浏览器 Case 一对一对应、复跑或补充最小 E2E、按需录制验收视频、排查登录/启动/等待/选择器/真实服务问题，并把已验证解法写回经验。"
---

# Web E2E

把已经跑通的 Web E2E 能力维护起来，让下一次执行先复用经验，而不是重新探索。

本 Skill 不拥有 Todo、Durable、PR 或全局交付状态。它只维护四件事：

- 当前任务与真实验收 Case 的一对一关系；
- 已经验证可用的运行入口；
- 普通运行与可选录像运行的真实结果；
- 运行中遇到的问题、根因和下次可直接复用的解法。

## 先读取经验

每次使用时，先完整读取同目录的 `experience.local.md`，再查看目标项目当前源码和运行态。

```bash
SKILL_NAME="web-e2e"
DIR="${CLAUDE_SKILL_DIR:-}"
[ -z "$DIR" ] && DIR="$(dirname "$(find "$HOME/.codex" "$HOME/.claude" -name SKILL.md -path "*/$SKILL_NAME/*" 2>/dev/null | head -1)")"
[ -z "$DIR" ] && DIR="$HOME/.codex/skills/$SKILL_NAME"
EXP="$DIR/experience.local.md"

[ -f "$EXP" ] && sed -n '1,360p' "$EXP" || echo "尚无本地经验；本次完成后创建"
```

读取时优先寻找：

- 与当前项目和 Case 匹配的已验证命令；
- 运行前置条件和真实副作用；
- 最近一次验证日期与对应代码版本；
- 已知现象、根因、有效解法和无效尝试；
- 测试结束后的清理要求。

经验和当前源码冲突时，以当前源码和本次验证为准，并在结束后修正旧经验。

## 维护一对一验收方案

用户准备把一个 Web 开发任务交给长时间执行时，为该任务保留一个对应的 E2E 验收方案。方案只需让后续 Agent 明白：

- 用户最终要看到什么结果；
- 现有哪个 Case 可以验证，或者需要补哪个 Case；
- 应运行什么入口；
- 哪些外部条件和副作用需要提前知道。

不要为了形式填写大而全的合同。简单任务可以只是一段提示词；脆弱的真实链路再补充必要细节。

E2E 的价值是提供机器可执行的验收终点。是否进入 Durable、Doing 或 Done 由对应任务系统决定，不在本 Skill 中定义。

## 按需录制 E2E 视频

调用方或用户要求录制 Web E2E 时，完整读取并执行 [video-evidence.md](references/video-evidence.md)。先让普通 E2E 稳定通过，再录制同一个 Case。

- 本 Skill 只负责 Web E2E 录像；原生移动端应使用目标平台的 E2E 或录屏能力。
- 输出稳定 MP4 绝对路径、媒体校验和对应 Case，供终端或上层编排消费。
- 运行时存在 Happy/Paws 文件发送能力时可以发送同一文件；发送、移动端确认和 PR 挂载属于交付适配器，不改变 E2E verdict。
- 视频证明交互时序，不替代 UI Before / After 图片。

没有录像要求时不要把转码、上传或手机确认加入固定完成条件。

## 优先复用，不重新发明

目标项目已经存在 Case 时：

1. 先定位测试、配置、启动脚本和 package script。
2. 对照本地经验确认入口仍然成立。
3. 直接复跑已验证入口；只有失效时才重新探索。
4. 区分产品失败、测试代码失败和环境失败。

不要因为能手工点击就绕开已有自动化，也不要因为某次等待很久就立即重写整个 Harness。

涉及生产账号、真实消息、创建数据或其他明显副作用时，在真正运行前告诉用户本次会产生什么，并取得当前任务范围内的授权。用户只要求整理或维护经验时，不要擅自运行昂贵 Case。

## 解决问题后立即写回

每次执行结束后检查 `experience.local.md` 是否需要更新。以下内容值得沉淀：

- 下次仍可能遇到的现象；
- 已确认的根因，而不只是猜测；
- 已经真实验证的解决方式；
- 可直接复用的命令、选择器、等待信号或清理方式；
- 适用项目、适用 Case、代码版本和最近验证日期。

不要沉淀：

- 一次性的逐步日志；
- 没有验证的猜测；
- 模型本来就知道的 Playwright 常识；
- 密钥、令牌、验证码和登录态文件内容；
- 与下次执行无关的长篇过程复述。

按 [references/experience-writing.md](references/experience-writing.md) 判断如何新增、修正或淘汰经验。不要机械追加互相矛盾的记录。

## 让经验持续进化

经验是当前最佳事实，不是不可修改的历史档案：

- 已有解法再次成功：更新最近验证日期和证据。
- 已有解法失效：先标记失效范围，再写入新根因和新解法。
- 同一经验跨多个项目成立：提炼为本文件中的通用原则。
- 只与某个项目、机器或账号有关：留在 `experience.local.md`。
- 自动化 Case 已把坑永久消除：将经验压缩为“由哪个测试或脚本保护”，避免保留过时排障步骤。

每次写回都要让下一位 Agent 更快抵达结果，而不是让经验文件变得更长。

## 交付

完成一次 E2E 维护或复跑后，向用户说明：

- 哪个一对一 Case 已具备或已运行；
- 最短复跑入口；
- 本次是否产生真实副作用；
- 发现了什么新问题；
- 哪些经验已写回，下一次可以少走什么弯路。

向上层编排返回 `case`、`status`、`evidence`、`artifacts`、`risks` 和 `next`。本 Skill 不自行创建 PR、等待 CI、执行交互评审或合并。

视频、截图、Trace 和报告按当前任务价值决定；明确要求录像时按视频 reference 生成并校验 MP4。