playwright

Playwright

概述

Playwright 是一个适用于 Node.js 和 Python 的浏览器自动化框架，通过统一的 API 支持 Chromium、Firefox 和 WebKit。它提供自动等待、以 Web 为先的断言以及完全隔离的测试环境，确保端到端测试可靠运行。

适用场景： 浏览器自动化、网页抓取、生成截图/PDF、API 测试、配置 Playwright Test、排查 Playwright 错误、隐身模式和绕过反机器人机制。

不适用场景： 简单的 HTTP 请求（使用 fetch）、单元测试（使用 Vitest/Jest）、大规模无服务器网页抓取（考虑使用 Cloudflare Browser Rendering）。对于 E2E 测试架构（页面对象模型、CI 分片、测试组织、身份验证模式），请使用 e2e-testing 技能。

快速参考

模式	API / 配置	要点
基本测试	test('name', async ({ page }) => {})	自动等待、以网页状态为准的断言、测试隔离
定位器	page.getByRole() / page.locator()	优先使用角色/标签/文本选择器，而非 CSS
断言	expect(locator).toBeVisible()	自动重试，可配置超时时间
API 测试	request fixture / apiRequestContext	发送 HTTP 请求并验证响应
Aria 快照	expect(locator).toMatchAriaSnapshot()	通过 YAML 验证无障碍树结构
类断言	expect(locator).toContainClass('active')	匹配单个 CSS 类名（v1.52+）
可见性筛选器	locator.filter({ visible: true })	仅匹配可见元素（v1.51+）
测试步骤	test.step('name', async (step) => {})	超时、跳过和附件（v1.50+）
隐身模式	playwright-extra + 隐身插件	修补 20 多种检测向量
已认证会话	context.cookies() + addCookies()	保存/恢复 Cookie 和 IndexedDB，以便持久化
截图	page.screenshot({ fullPage: true })	先等待关键元素加载
PDF 生成	page.pdf({ format: 'A4' })	仅限 Chromium，设置 printBackground: true
时钟 API	page.clock	在测试中冻结、快进或模拟时间
无障碍断言	toHaveAccessibleName、toHaveRole	无需依赖 axe-core 的原生断言
视口断言	expect(locator).toBeInViewport()	断言元素位于可见视口内
仅运行已更改的测试	--only-changed=$GITHUB_BASE_REF	仅运行自基准分支以来有更改的测试文件
Docker	mcr.microsoft.com/playwright:v1.58.2-noble	使用 --init --ipc=host 标志
调试方法	page.consoleMessages() / page.requests() (v1.56+)	无需事件监听器
Speedboard	HTML 报告器（v1.57+）	找出耗时较长的测试和瓶颈
Playwright Agents	npx playwright init-agents	用于大模型驱动测试的规划器、生成器和修复器
不稳定测试检测	--fail-on-flaky-tests（v1.50+）	CI 中遇到不稳定测试时返回退出代码 1
修改实时响应	route.fetch() + route.fulfill()	拦截真实响应、调整 JSON 并返回
软断言	expect.soft(locator)	失败时不中止测试，在最后汇总报告
重试块	expect(async () => {}).toPass()	默认超时时间为 0（无限）——务必设置超时
自定义匹配器	expect.extend() / mergeExpects()	定义或组合自定义断言方法
可操作性检查矩阵	各操作的自动等待检查	click：全部 5 项检查，fill：3 项，focus/blur：无
测试修饰符	test.fixme() / test.fail() / test.slow()	fixme=跳过并跟踪，fail=断言失败，slow=3 倍
并行模式	test.describe.configure({ mode: 'serial' })	每个 describe 块可设为串行、并行或默认模式
拆卸项目	设置项目上的 teardown 选项	所有依赖项完成后自动清理

常见错误

错误	正确做法
使用 CSS 选择器而非角色选择器	优先使用 getByRole、getByLabel、getByText，以增强稳定性
未关闭浏览器	始终在 finally 代码块中执行 await browser.close()
使用 setTimeout 等待	使用定位器自动等待或 waitForLoadState
在 CI 代码中遗留 page.pause()	使用 if (!process.env.CI) 进行保护，否则会导致 CI 无限挂起
点击前未等待	使用带内置自动等待功能的 locator().click()
测试间共享状态	每个测试都通过 fixture 获取全新的上下文
测试实现细节	断言用户可见的行为，而非 DOM 结构
对动态内容使用硬编码等待	等待选择器出现或内容稳定
断言缺少 await	所有 expect() 断言都会返回 Promise，必须等待
所有抓取操作使用相同的 user agent	高流量抓取时轮换 user agent
在依赖时间的测试中使用 setTimeout	使用 page.clock API 冻结或快进时间
为简单的无障碍检查安装 axe-core	使用原生的 toHaveAccessibleName/toHaveRole 断言
使用 toPass() 时未指定超时	始终传入 { timeout: 10_000 }——默认值为 0（永久等待）
Service Worker 静默阻止 page.route()	使用 MSW 时，在上下文配置中设置 serviceWorkers: 'block'
对自动补全/防抖输入使用 fill()	使用 pressSequentially()，并可选择设置延迟，以逐键处理
storageState 未保留 sessionStorage	storageState 只保存 Cookie 和 localStorage——通过 addInitScript() 注入 sessionStorage

委派

• 选择器问题排查：使用 Explore Agent
• 测试模式审查：使用 Task Agent
• 代码审查：委派给 code-reviewer Agent

关于端到端测试架构、Page Object Model 模式、CI 分片策略、身份验证流程、视觉回归工作流或测试组织，请使用 e2e-testing 技能。

参考资料

• 快速入门与安装
• 端到端测试模式与断言
• 选择器策略与最佳实践
• 配置与 Docker 部署
• Docker 与 CI
• 调试方法与性能分析
• 常见自动化模式
• 隐身模式与反机器人绕过
• 已知问题与解决方案
• 针对特定网站的拦截与绕过方法
• 常见问题排查
• 网络测试、模拟与 API 模式
• 输入模式、可操作性与测试修饰符
• 高级断言、轮询、自定义匹配器与注释
• 高级主题：MCP、AI Agent、并行上下文