playwright-skill

为什么要用

核心特性

基于角色和无障碍的定位符模式（避免 CSS/XPath 脆弱性）
网络 stub 和响应模拟的习语
用于跨测试复用 auth 状态的 fixtures
通过追踪查看器进行追踪捕获和调试
并行化和分片指导
消除不稳定性：web-first 断言、重试策略

实时演示

实际使用效果

playwright-skill-2.replay ▶ 就绪

0/0

安装

作者仓库 · Claude Skills 官方文档

使用场景

实战用法： playwright-skill

如何编写可维护的首个 E2E 测试

👤 首次在项目中添加 Playwright 的开发者 ⏱ ~30 min beginner

何时使用： 你有一个 staging URL 和登录流程；在扩展之前你想要一个扎实的测试。

步骤

描述流程

为 staging.example.com 的登录编写 Playwright 测试：邮箱、密码、预期仪表板标题。只使用基于角色的定位符。✓ 已复制

→ 使用 getByRole、getByLabel 的测试；没有 .class 或 xpath
添加 auth 复用 fixture

将登录转换为可复用的 auth fixture，以便其他测试跳过登录。✓ 已复制

→ 基于 storageState 的 fixture + globalSetup
确保不会出现不稳定性

检查测试中的 waitFor* 反模式；切换到 web-first 断言。✓ 已复制

→ 使用 expect(locator).toBeVisible() 而不是 waitForSelector

结果： 一个扎实的首个测试加上整个测试套件继承的 fixture。

注意事项

Claude 倾向于使用 page.waitForTimeout — 明确告诉 skill：不要任意等待，使用 web-first 断言

Stub 后端 API 以测试前端边界情况

👤 测试空/错误/加载状态的前端工程师 ⏱ ~25 min intermediate

何时使用： 你无法轻松将真实后端放入每个状态。

步骤

Stub 端点

Stub GET /api/orders 以返回空数组，然后断言空状态渲染。✓ 已复制

→ route.fulfill 带 JSON body；对空状态元素的断言
按测试改变响应

参数化 stub：一个测试用于 500 错误，一个用于超时，一个用于部分数据。✓ 已复制

→ 三个测试共享一个 helper

结果： 在不接触后端的情况下获得边界状态覆盖。

注意事项

Stub 在测试之间泄露 — 在 beforeEach 或 fixture 作用域中设置，而不是在模块级 hook 中

使用追踪查看器调试不稳定的测试

👤 在 CI 中对不稳定测试套件进行分类的工程师 ⏱ ~45 min intermediate

何时使用： 一个测试在本地通过，在 CI 中 5% 的时间失败。

步骤

在重试时捕获追踪

在 playwright.config.ts 中配置追踪为 'on-first-retry'。✓ 已复制

→ Config diff
分析追踪

从失败的 CI 运行中下载 trace.zip；给我解释一下与成功运行相比有什么不同。✓ 已复制

→ 网络/DOM 时序中的具体 diff
修复

基于追踪，提议最小改动以消除不稳定性。✓ 已复制

→ 特定定位符或断言改变，而不是盲目的 sleep

结果： 一个消除了不稳定性的测试，带有文档化的根本原因。

注意事项

通过增加超时来处理不稳定性 — 大多数不稳定性是隐藏的竞态条件——追踪通常会显示缺少的 await

组合

与其他 MCP 搭配，撬动十倍杠杆

playwright-skill-2 + seo-audit-skill

Playwright 捕获页面，SEO 审计对 JS-heavy 应用的渲染 HTML 进行检测

使用 Playwright 进行身份验证并捕获已登录页面，然后对每个页面运行 seo-audit。✓ 已复制

工具

此 MCP 暴露的能力

工具	输入参数	何时调用
Locator patterns	-	编写新的选择器
Network stubbing	-	测试前端边界状态
Fixtures & auth reuse	-	将测试套件扩展到 5 个以上
Trace analysis	trace.zip	调试不稳定性
Parallelism & sharding	-	在 CI 中运行超过 5 分钟的测试套件

成本与限制

运行它的成本

API 配额: 无
每次调用 Token 数: 测试生成：3-8k tokens
费用: 免费
提示: 手动生成一个测试，保存为模板，然后让 Claude 为其他测试遵循这个模板。

安全

权限、密钥、影响范围

凭据存储： 在 .env 中放置测试凭据（通过 dotenv）。永远不要提交包含生产 auth 的 storageState.json。

数据出站： 测试会命中你的目标 URL。skill 不会进行第三方调用。

storageState.json 包含会话 cookies。将其加入 .gitignore，不要公开作为 CI 工件上传。

故障排查

常见错误与修复

测试仅在 CI 上不稳定

启用追踪配置 'on-first-retry' 并分析失败尝试的追踪。

验证： npx playwright show-trace trace.zip

getByRole 找不到明显存在的元素

元素可能缺少可访问的名称。使用 Playwright Inspector 查看计算出的角色/名称。

验证： npx playwright test --ui

登录 fixture 在本地工作，在 CI 中失败

CI 可能需要 --headed=false 和显式浏览器安装。在 CI 中运行 npx playwright install --with-deps。

替代方案