Playwright 是什么
Playwright 是微软开源的浏览器自动化与测试框架：用同一套 API 驱动 Chromium、Firefox 与 WebKit，默认自动等待元素就绪，并内置测试运行器、断言、重试、报告与 trace 回放。它提供 TypeScript、Python、Java、.NET 语言绑定，支持有头与无头模式、多浏览器并行、设备模拟与网络拦截。与 Selenium 相比，Playwright 将等待、定位与断言收敛为一等公民的定位器 API，写出的用例更短、更稳；与 Cypress 相比，它不在浏览器进程内运行，天然支持多标签页、多域与跨语言。
基本信息
| 发布方 | Microsoft，开源（Apache 2.0） |
|---|---|
| 支持浏览器 | Chromium、Firefox、WebKit（引擎级驱动） |
| 语言绑定 | TypeScript/JavaScript、Python、Java、.NET |
| 核心机制 | 定位器自动等待、web-first 轮询断言 |
| 工具链 | 测试运行器、codegen 录制、UI 模式、trace 查看器 |
| 安装方式 | npm init playwright@latest 或 pip install playwright |
典型使用场景
- 端到端测试：覆盖登录、下单等关键业务链路
- 跨浏览器回归：同一套用例在三大引擎上验证兼容性
- 失败定位：CI 失败后打开 trace 回放操作现场与网络请求
- 接口辅助验证：用内置 request 上下文对 API 直接断言，与 UI 用例互证
- 设备模拟：用内置设备描述对移动端视口与触控行为做冒烟
- 视觉回归：对截图做基线对比，捕获意外样式变化
起步命令
起步命令
npm init playwright@latest # 初始化项目并安装浏览器二进制
npx playwright test # 无头运行全部用例
npx playwright test --headed # 有头模式观察真实操作过程
npx playwright test --ui # UI 模式逐步调试
npx playwright show-report # 打开 HTML 报告
npx playwright show-trace trace.zip # 回放失败现场的完整 trace最小用例
最小用例
# 打开页面并等待标题就绪
await page.goto('https://example.com');
await expect(page).toHaveTitle(/Example/); # 自动轮询直到超时
# 按可访问性角色定位并点击
await page.getByRole('button', { name: '登录' }).click();
# 断言无 toast 报错出现
await expect(page.locator('.toast-error')).toHaveCount(0);核心概念
| 概念 | 说明 | 使用要点 |
|---|---|---|
| 定位器 Locator | 对元素查询的声明式描述，惰性求值 | 优先角色与标签等语义定位 |
| 自动等待 | 动作与断言执行前自动等待元素可交互 | 无需手写 sleep 或显式轮询 |
| web-first 断言 | 内置断言反复检查直到通过或超时 | 断言失败信息自带实际值 |
| trace | 记录操作、网络与快照的回放文件 | CI 失败时第一手排查材料 |
| 重试 | 对失败用例按策略重跑 | 只有判定为环境抖动的用例才配置 |
首次使用需安装浏览器二进制：npx playwright install --with-deps；Linux 容器里缺少系统依赖时，--with-deps 会一起安装，否则 WebKit 等浏览器无法启动。
定位优先级建议：可访问性角色与标签（getByRole/getByLabel）优于文本，文本优于 CSS，CSS 优于 XPath；细节见 playwright-locators 条目。
CI 建议配置 trace 为 on-first-retry：只在失败并进入重试时保留现场，既拿到排查材料又不让每次运行都产生大量附件。
版本管理：把 @playwright/test 与浏览器版本一起固定（playwright install 会安装与库匹配的浏览器版本），随意升级可能改变断言行为与默认超时。
大规模套件用分片并行：npx playwright test --shard=1/3 配合 CI 多机执行，同时复核测试数据隔离是否支撑并发。
登录等前置链路不必每个用例重跑：用 setup 项目登录一次并保存 storageState，其余用例直接复用登录态，套件时长能缩短一大截。
需要构造异常分支时，优先用 route 拦截网络请求并返回指定响应，比依赖后端真实故障环境更可控、可重复。