用途
本技能用于增强 Claude 在 Playwright 测试领域的专业能力,重点覆盖 AI 默认容易做错或忽略的高级场景。它不教授基础 API,而是提供经过实战检验的模式,帮助避免生产环境中的痛苦问题。
适用场景包括:
- 编写 Playwright 端到端测试
- 调试不稳定的测试或间歇性 CI 失败
- 设置认证(storageState、全局 setup、多角色项目)
- 配置 CI 流水线(分片、缓存、Docker 容器)
- 实现视觉回归/截图对比
- 在复杂场景(iframe、service worker)中模拟 API 路由或拦截网络
- 编写测试基础设施(自定义 fixture、页面对象、共享工具)
- 为 React/Vue/Svelte 设置 Playwright 组件测试(CT)
- 从 Cypress、Puppeteer 或 Selenium 迁移到 Playwright
不适用于:不涉及 Playwright 的 Jest/Vitest 单元测试;与测试自动化无关的通用 Puppeteer 脚本;项目首次搭建。
主要能力
首次激活配置
首次激活时检查技能目录下是否存在 config.json,若不存在则询问用户以下问题并保存答案:
- baseURL(默认 http://localhost:3000)
- testDir(默认 ./tests)
- authStrategy(storageState | none | per-test-login)
- ciProvider(github-actions | gitlab-ci | circle-ci | other)
- browsers(数组,如 chromium、firefox、webkit)
- screenshotBaseline(linux | macos | docker)
这些值用于生成正确的配置片段,避免每次会话重复询问。
十个高价值陷阱
-
storageState 不包含 sessionStorage:context.storageState() 只保存 cookies 和 localStorage,静默忽略 sessionStorage。若应用将认证令牌存于 sessionStorage(许多 SPA 如此),保存的状态文件看似有效但测试会因未认证重定向而失败。修复:在全局 setup 中用 page.evaluate() 额外导出 sessionStorage,再通过自定义 fixture 中的 addInitScript 恢复。
-
page.route() 不拦截 iframe 请求:page.route('**/api/*', handler) 只拦截顶层页面的请求,iframe 内的 API 调用对它不可见,需使用 context.route() 在浏览器上下文级别拦截。这在嵌入支付表单(Stripe Elements、PayPal)和第三方组件时影响很大。
-
截图基线依赖操作系统、浏览器和 DPI:在 macOS 上生成的快照在 Linux CI 中会因字体渲染、亚像素抗锯齿和 DPI 差异而失败。始终在 CI 使用的同一环境中生成基线。最佳实践:在 CI 使用的同一 Docker 容器内运行 --update-snapshots,并提交结果。
-
fullyParallel + 共享数据库 = 静默数据损坏:启用 fullyParallel: true 时,同一文件内的测试并发运行。若两个测试用同一邮箱创建用户,一个会因重复键错误失败,看起来像测试 bug。修复:为每个测试生成唯一测试数据(如 crypto.randomUUID() 作为邮箱前缀),或使用每个测试回滚的数据库事务。
-
workers 与 shards 不同:workers: 4 表示单机 4 个线程共享内存/数据库;--shard=1/4 表示 4 台独立机器。设置 workers: 1 并不能防止分片冲突。若测试共享全局状态(单一测试用户、共享 API 密钥),即使每个分片只有一个 worker 也会跨分片冲突。
-
水合(hydration)会破坏点击处理器:在 SSR 应用(Next.js、Nuxt)中,Playwright 找到服务端渲染的按钮并点击,但 React 尚未水合,点击处理器未附加,点击静默无效。Playwright 的自动等待检查可见性和稳定性,不检查水合。修复:在水合后添加 data-hydrated 属性并等待它,或使用 page.waitForFunction(() => document.querySelector('[data-hydrated]'))。
-
page.clock 需要显式安装:page.clock.install() 必须在导航到页面之前调用。如果在 page.goto() 之后调用,应用已调度的定时器不会被捕获。时钟也不影响 Web Workers,worker 中的定时器仍使用真实时间。
-
expect(locator).toHaveText() 默认做子串匹配:await expect(locator).toHaveText('Hello') 在元素包含 "Hello World" 时也会通过,这与 Jest 的 toBe 不同。精确匹配需使用 toHaveText('Hello', { exact: true }) 或正则 toHaveText(/^Hello$/)。Claude 默认写非精确形式,导致假通过。
-
route.fulfill() 的 json 选项会静默设置 content-type:使用 route.fulfill({ json: data }) 时,Playwright 自动设置 Content-Type: application/json。若同时手动传入 contentType,手动值胜出但 json 仍会被字符串化。若同时传入 body 字符串和 json,json 选项优先。这些优先级规则从类型定义中不明显。
-
直接使用 browser.newPage() 会破坏测试隔离:若通过 browser.newPage() 而非 page fixture 创建页面,Playwright 不会创建隔离的 BrowserContext,页面会与同一浏览器的其他页面共享 cookies、localStorage 和缓存。始终先使用 browser.newContext(),再 context.newPage()。
非显而易见的模式
- 多角色认证与项目依赖:通过 projects 配置 auth-setup 项目,admin 和 member 项目依赖它并各自使用不同的 storageState。完整设置(含令牌刷新和 OAuth 模拟)见 references/auth-patterns.md。
- 原子等待网络与操作:错误做法是先点击再等待响应,存在竞态条件;正确做法是用 Promise.all 同时注册等待和触发操作。
- 修改响应而不替换:通过 route.fetch() 获取响应,修改 JSON(如截取前 2 项),再用 route.fulfill({ response, json }) 返回。
- 全局禁用动画:在配置中设置 contextOptions: { reducedMotion: 'reduce' };对于忽略 prefers-reduced-motion 的应用,注入 CSS 强制动画和过渡时长为 0。
/careful 破坏性命令保护
用户调用 /careful 时,以下命令执行前会弹出确认提示:
- npx playwright test --update-snapshots(覆盖所有基线截图)
- rm -rf test-results/(删除追踪和截图产物)
- rm -rf .auth/(删除保存的认证状态,破坏依赖项目)
- npx playwright install --force(重新下载所有浏览器,约 1.5GB)
未调用 /careful 时正常执行,这是可选的安全网。
技能记忆
跨会话跟踪测试运行模式,每次运行后检查并更新 .playwright-skill/run-log.json,记录 lastRun、flakyTests、avgDuration 和 failurePatterns(如 timeout、strict-mode-violation、navigation 计数)。利用这些数据主动建议修复。若同一测试在 3 次以上运行中出现在 flakyTests 中,标记并建议加载 references/flaky-test-playbook.md。
参考文档(按需加载)
- references/locator-strategies.md:定位器优先级指南、过滤、链式、iframe/Shadow DOM
- references/auth-patterns.md:storageState 生命周期、令牌刷新、多角色测试、OAuth 模拟
- references/flaky-test-playbook.md:诊断流程图、7 个根因、基于追踪的调试
- references/ci-optimization.md:分片计算、浏览器缓存、Docker 陷阱、产物策略
- references/component-testing.md:CT 模式设置、挂载、props 序列化、模拟模式
配套技能检查
首次激活时检查已安装的配套技能(通过 ls 多个可能的技能目录),与 frontmatter 中的 recommended_skills 对比。缺失的提及一次并提供安装命令:npx skills add AbsolutelySkilled/AbsolutelySkilled --skill <name>。若 recommended_skills 为空或所有配套已安装则跳过。
解锁完整技能图
仅当用户未安装 skill-suggestor 时显示此部分(通过 npx skills ls --json 或已安装列表检查)。若已安装则完全跳过。安装 skill-suggestor 可自动发现高价值技能组合:npx skills add AbsolutelySkilled/AbsolutelySkilled --skill skill-suggestor。