原理与核心概念

⚡ 为何更快？

传统 Selenium 通过 WebDriver 协议 → Driver 进程 → 浏览器的三层架构通信。Playwright 直接通过浏览器原生协议通信，减少中间层，延迟更低。

🔒 为何更稳？

Playwright 使用浏览器团队维护的调试协议，能接收浏览器的精确事件（如网络请求完成、DOM 变更），从而实现可靠的自动等待，避免竞态条件。

Playwright

入口对象，通过 sync_playwright() 或 async_playwright() 创建。它是整个 API 的起点，提供对三种浏览器类型的访问。

from playwright.sync_api import sync_playwright
with sync_playwright() as pw:
    # pw.chromium / pw.firefox / pw.webkit

Browser

代表一个浏览器实例。可以通过 launch() 启动本地浏览器，或通过 connect() 连接远程浏览器。

browser = pw.chromium.launch(
    headless=True,
    slow_mo=100  # 慢速模式，便于调试
)

BrowserContext

独立的浏览器会话，类似隐身模式窗口。每个 Context 有独立的 Cookie、LocalStorage、Session。是实现测试隔离的关键。

context = browser.new_context(
    viewport={"width": 1280, "height": 720},
    locale="zh-CN",
    timezone_id="Asia/Shanghai"
)

Page

代表浏览器中的一个标签页。所有页面操作（导航、点击、输入、截图等）都通过 Page 对象完成，是最常用的 API。

page = context.new_page()
page.goto("https://example.com")
page.click("text=登录")
page.fill("#username", "admin")

Locator

Playwright 推荐的元素定位方式。Locator 是惰性的，每次操作时重新查找元素，天然防止陈旧引用问题。

# 推荐：使用 Locator（惰性查找）
btn = page.locator("button.submit")
btn.click()  # 每次操作重新定位

# 更推荐：使用语义化定位
page.get_by_role("button", name="提交").click()

Auto-waiting（自动等待）

Playwright 在执行操作前会自动等待元素满足条件：可见、稳定、已启用、接受事件。无需手动添加 sleep 或显式等待。

# 不需要 time.sleep() 或 WebDriverWait
# Playwright 自动等待按钮可点击
page.click("#submit-btn")

# 等待特定条件
page.wait_for_selector(".result", state="visible")

🎨 选择器引擎

• css= CSS 选择器（默认）
• text= 文本内容匹配
• xpath= XPath 表达式
• get_by_role() 无障碍角色定位
• get_by_text() 文本定位
• get_by_label() 标签定位
• get_by_test_id() data-testid 定位

🛠 开发者工具

• Codegen — 录制操作生成代码
• Trace Viewer — 时间线回放调试
• Inspector — 交互式调试器
• VS Code 插件 — 编辑器集成
• Screenshots — 页面与元素截图
• Video Recording — 自动录屏
• PDF Generation — 页面导出 PDF

🌐 网络控制

Playwright 提供强大的网络层控制能力：

# 拦截并修改请求
def handle_route(route):
    if "analytics" in route.request.url:
        route.abort()  # 拦截广告/分析
    else:
        route.continue_()

page.route("**/*", handle_route)

# Mock API 响应
page.route("**/api/users", lambda r:
    r.fulfill(json={"users": []})
)

📷 追踪与调试

Trace Viewer 记录每一步操作的快照、网络请求和控制台日志：

# 开启追踪
context.tracing.start(
    screenshots=True,
    snapshots=True,
    sources=True
)

# ... 执行操作 ...

# 保存追踪文件
context.tracing.stop(path="trace.zip")

# 查看: playwright show-trace trace.zip

端到端测试 (E2E Testing)

Playwright 最主要的使用场景。结合 pytest-playwright 插件，编写可靠的跨浏览器端到端测试，模拟真实用户操作，验证完整业务流程。

网页爬虫与数据采集

处理 JavaScript 动态渲染的页面，等待异步数据加载完成后提取内容。支持拦截网络请求直接获取 API 数据。

自动化办公流程

自动登录企业系统、批量填写表单、自动下载报表、定时截图监控仪表盘等重复性浏览器操作。

视觉回归测试

对页面进行截图并与基准图对比，检测 UI 变更。支持全页面截图、元素截图和自定义裁剪区域。

性能与安全测试

拦截网络请求分析加载性能，模拟慢网络环境，检测 XSS 漏洞，测试认证授权流程。

PDF 生成与报告

将网页渲染为高质量 PDF，适用于自动生成发票、报告、合同等文档。支持自定义页面大小和页眉页脚。

推荐使用 Playwright 的场景

• 新项目需要跨浏览器 E2E 测试
• 团队使用 Python 且需要浏览器自动化
• 需要处理复杂场景（多标签页、iframe、文件上传下载）
• 需要稳定的 CI/CD 集成
• 从 Selenium 迁移到现代框架
• 网页数据采集（动态渲染页面）

可能不适合的场景

• 已有大量 Selenium 测试且运行良好
• 需要测试移动原生应用（考虑 Appium）
• 纯前端 JS 项目且团队偏好 Cypress
• 需要 IE 浏览器支持
• 需要 Selenium Grid 的大规模分布式能力