playwright-skill

Playwright Skill · MCP-first 浏览器操作 playbook

0. 设计转向(v8 vs v7)

v7 是个完整的 Playwright test runner(flows/ playwright.config.ts package.json node_modules),写 spec 文件、跑 npx playwright test、拿 exit code。

v8 砍掉这一切。skill 只剩两样:

• config/ — 项目适配层(baseURL / 登录 selector / 凭证)
• SKILL.md — 给 Claude 看的操作 playbook

实际开浏览器是用 MCP playwright 工具(mcp__playwright__browser_*),由对话里的 Claude 边看 browser_snapshot 边操作。截图落 runtime/screenshots/。

1. 铁律(读到必须执行)

1. 不写 spec 文件,不跑 playwright test。需要操作浏览器一律用 MCP browser_* 工具。
2. 所有项目相关参数从 config/playwright-skill.config.json 读,不写死 localhost:5173 / /login / 欢迎回来 等。
3. 登录开关:auth.required=true 才走登录;false 时跳过登录直接进站。
4. 登录优先级:
   • 先 browser_navigate 到 runtime.baseURL + auth.selectors.loginPagePath 或 runtime.homePath,
   • browser_snapshot 看当前 URL / DOM,命中 runtime.loginUrlPatterns 任一项 → 登录页。
   • 是登录页就读 config/credentials.local.json 填账号密码,按 selectors.submit 点登录,处理 orgSelectDialog,等 successCheck.text 出现。
5. MCP 操作优先用 ref(snapshot 里的元素引用),而不是 selector。selector 是 fallback。
6. 截图只能写 runtime/screenshots/,通过 browser_take_screenshot 的 filename 参数指定。
7. 凭证文件 config/credentials.local.json 随项目一起提交,字段 {username, password}。
8. 不修改项目根的任何文件(tests/ package.json 等本 skill 都不碰)。

---

2. 目录结构

.claude/skills/playwright-skill/
├── SKILL.md                                       本文件
│
├── config/                                        项目适配层
│   ├── playwright-skill.config.schema.json          配置合同
│   ├── playwright-skill.config.example.json         示例(commit)
│   ├── playwright-skill.config.json                 实际生效(随项目 commit,首跑从 example 复制)
│   ├── credentials.local.example.json               凭证示例(commit)
│   └── credentials.local.json                       实际凭证(随项目 commit)
│
└── runtime/                                       ⚠️ gitignore — 临时产物
    └── screenshots/                                 MCP 截图落这

无 lib/、无 flows/、无 playwright.config.ts、无 node_modules、无 package.json。