做了几年 Web 端自动化测试工具从 Selenium 换到 Puppeteer 再换到 Cypress说实话每个都有让人又爱又恨的地方。Playwright 是这几年里少数让我愿意把测试代码当生产代码来写的框架——它的自动等待机制、多浏览器驱动、Trace Viewer、codegen 这些能力不是简单加几个 API而是把大量从前需要测试工程师手工绕行的坑在框架层直接填平了。这篇文章不讲 API 手册那些翻官方文档就能查到。我想分享的是把 Playwright 真正用进生产级项目时的最佳实践用例结构怎么搭、定位怎么写才又稳又快、测试数据怎么隔离、并行执行怎么跑、线上偶发失败怎么快速定位。适合刚上手 Playwright 的测试开发也适合已经在用、但天天被不稳定用例折磨的团队参考。文章里所有方案都是我实打实验证过的不整虚的。1. 动手写用例前先把 Playwright 的底层逻辑搞清楚1.1 自动等待别再写 sleep(3) 了Playwright 和 Selenium 最大的区别之一就是它的操作命令默认带可操作检查actionability check。点击一个按钮时Playwright 会等这个按钮满足这几个条件元素已附加到 DOM、可见、稳定不持续移动、能接收事件、没有被遮挡。这套机制意味着你不需要在每一步前面加waitForTimeout(3000)也不需要写轮询等待函数。很多从 Selenium 转过来的同事上来第一件事是给每个操作加 sleep把 Playwright 的自动等待完全架空——这是最可惜的用法。我个人的习惯是默认完全信任自动等待只在极端场景下手动等待具体条件。比如一个表格要等接口返回后才渲染直接用await expect(page.getByRole(table)).toContainText(预期数据);这个断言本身就是等待——Playwright 的 expect 断言默认会重试 5 秒可配置直到条件满足或超时。你不需要先waitForResponse再断言把两者拆开反而更容易踩空。1.2 用户能看到什么你就定位什么Playwright 的选择器体系是所有框架里我体验最好的核心原则可以总结成一句话站在用户视角写定位。用户不会关心某个按钮的 CSS class 是不是btn-primary-hover-v2用户关心的是这个按钮叫提交。所以定位优先级应该这么排按角色和名称getByRole(button, { name: 提交 })按可访问文本getByText(订单编号)按预设的测试标识>import { test as base, expect } from playwright/test; export const test base.extend({ // 每个用例自动登录并返回带会话的页面对象 authedPage: async ({ page }, use) { await page.goto(/login); await page.getByLabel(账号).fill(process.env.TEST_USER!); await page.getByLabel(密码).fill(process.env.TEST_PASS!); await page.getByRole(button, { name: 登录 }).click(); await expect(page).toHaveURL(/\/dashboard/); await use(page); }, });然后在用例里直接test(..., async ({ authedPage }) {...})即可。相比beforeEachfixture 的好处是按需注入——只有声明了authedPage的用例才执行登录逻辑没声明的不登录节省执行时间而且依赖关系一目了然。2.3 Page Object 到底还学不学Page Object ModelPOM是 Selenium 时代最经典的设计模式Playwright 下仍然有价值但要注意别写成为了 POM 而 POM。我的建议是如果页面交互复杂且复用到多个用例才抽 Page Object。如果只是单一流程的用例硬套 Page Object 只会制造一堆没人维护的中间类。搭配上 fixture 之后更自然的做法是把页面封装和测试前置条件一起放进 fixture而不是单独维护一个巨大的xxxPage.ts。用 POM 的唯一硬性要求所有暴露给用例的方法必须返回能继续断言的东西。比如await orderPage.submit()返回的是PromisePage让用例还能继续对结果页做断言而不是返回 void否则用例和封装类之间就断层了。3. 定位与交互从能跑进化到跑得稳3.1 确定性定位的三条军规用例不稳定80% 的问题出在定位写得不够确定。我总结了三条军规团队里新人都先背这个再写用例一个定位器必须唯一命中一个元素否则 Strict Mode 会直接报错而不是侥幸跑过定位器最好不受页面渲染顺序影响比如用户可见文本、 aria 标签而不是第几个.item不要在一个长链路里不断.locator()套娃尽量使用page.getByRole()这类高内聚定位举一个反面例子// 不推荐依赖 DOM 嵌套层级和重复 CSS 类 await page.locator(.list .item:nth-child(3) .btn).click();推荐写法// 推荐直接描述第三个商品的购买按钮 const productItem page.getByTestId(product-item).nth(2); await productItem.getByRole(button, { name: 购买 }).click();第二个写法的好处是列表顺序变了、样式改了只要product-item标识还在用例就不用动。3.2 动态内容、iframe、滚动加载怎么处理动态加载是自动化测试里非常常见的翻车点。如果页面是滚动加载直接click一个在视口外的元素Playwright 会自动滚动它入视图所以大部分时候你不需要手动处理。真正需要手写的是滚动后触发接口再渲染的场景await page.mouse.wheel(0, 3000); await expect(page.getByText(加载完成)).toBeVisible();这里注意mouse.wheel之后不要立刻操作元素而是等一个渲染完成的标志。你等的应该是业务上的确定状态而不是等固定秒数。iframe 处理是 Playwright 做得非常顺手的地方。Selenium 时代切 frame 要用switchTo().frame()切错就找不到元素Playwright 直接用frameLocatorconst paymentFrame page.frameLocator(#payment-iframe); await paymentFrame.getByPlaceholder(卡号).fill(4242424242424242); await paymentFrame.getByRole(button, { name: 确认支付 }).click();注意frameLocator是惰性的它会等到 frame 出现才执行内部操作所以你不需要额外等待 frame 加载。唯一要确认的是 selector 是否正确指向 iframe 的外层标记。3.3 Codegen 的正确打开方式npx playwright codegen是很多新手最先接触的功能——打开浏览器手动点一遍代码就自动生成了。但这个功能我通常只用来做两件事快速探索定位符和生成初始骨架从来不直接复制生成的完整代码到用例里。为什么因为 codegen 生成的代码是过程导向的它会把你所有鼠标滑动、临时停顿、非必要点击全录进去导致用例冗长且脆弱。我的标准用法是用 codegen 定位到目标元素看它推荐的最优 locator 是什么复制这个 locator自己写干净的操作步骤手动补上断言比如我经常用 codegen 查某个按钮的getByRole名称到底怎么写查询完立即关掉。这样既利用了工具的效率又没有把工具的啰嗦带进代码。3.4 等接口还是等界面很多人纠结要不要等某个接口返回后再操作。我的经验是优先断言界面状态而不是等接口。理由很简单——接口返回不代表界面渲染完成response到了浏览器React/Vue 还要做 diff 和更新waitForResponse之后立刻操作依然可能撞上渲染中间态。Playwright 的expect断言自带重试界面状态到位了它自然就继续了。如果非要等接口我一般这么写const [response] await Promise.all([ page.waitForResponse(resp resp.url().includes(/api/order/create) resp.ok()), page.getByRole(button, { name: 提交订单 }).click(), ]);这里用Promise.all同时发起等待和点击避免先点击再等待时漏掉事件时序的问题。不过这也是兜底方案能靠断言解决就尽量不碰接口等待。4. 测试数据与隔离让每条用例都活在自己的世界里4.1 用例之间为什么必须零依赖自动化测试最怕用例顺序颠倒就失败。我见过一个项目测试必须按创建订单 → 查询订单 → 取消订单的顺序跑就是因为后面用例依赖前面用例产生的数据。一旦改成并行执行整个套件直接崩掉。最佳实践是每条用例自己造数据、自己清理数据。测试代码里不允许出现依赖上一条用例留下的状态这种隐性契约。Playwright 的每个 test 默认都是全新的 BrowserContextcookie、localStorage、缓存全部隔离这是框架给我们的最强保障一定不要主动破坏它。4.2 用 API 准备数据比用 UI 快一个量级如果每条用例都从头走 UI 流程去造数据执行时间会成倍增长。比如要测已登录用户取消订单与其用 UI 一步步下单不如直接调接口创建订单import { request } from playwright/test; test(取消订单, async ({ page }) { // 在用例里起一个独立的 API 请求上下文 const api await request.newContext({ baseURL: https://api.example.com }); const resp await api.post(/orders, { data: { productId: p_1001, quantity: 1 }, headers: { Authorization: Bearer ${token} }, }); const orderId (await resp.json()).id; await page.goto(/orders/${orderId}); await page.getByRole(button, { name: 取消 }).click(); await expect(page.getByText(订单已取消)).toBeVisible(); });用 API 造数并不违背端到端测试的本意——测的是前端与接口协作的结果而不是把前端所有流程都重走一遍。该用 UI 走流程的用例保留 UI数据准备类的操作全部抽到 API 层我实测下来整个套件耗时能缩短 40% 以上。4.3 StorageState登录态不要再跑一遍 UI 了大量用例需要登录态。如果所有用例都走一遍fill 账号密码 → 点击登录既慢又容易因为登录接口波动而批量失败。Playwright 官方推荐的方案是storageState把登录后的 cookie/localStorage 保存成文件后续用例直接复用。我通常在 CI 的前置任务里单独执行一次登录并保存状态然后所有用例套件读取这个存档// playwright.config.ts use: { storageState: ./e2e/data/auth/login-state.json, }生成存档的方式很简单写一个一次性脚本登录成功后调用page.context().storageState({ path: ./e2e/data/auth/login-state.json })。这里有个隐藏的好处存储态文件当成 fixture 版本管理后登录状态的变化可以 diff。哪天登录逻辑变了导致用例全挂你可以立刻从存档文件的变化看出问题排查效率极高。4.4 用例结束后的清理动作造了数据、注册了账号用例跑完要不要清理我的建议是测试环境的数据不用刻意清理但必须保证数据可重复创建。刻意清理反而容易引入清理失败导致后续用例失败的新问题。只要你的用例不依赖某条数据只存在一份脏数据堆积就不是自动化测试要解决的问题。如果某些数据存在唯一性校验比如手机号不能重复注册做法是注册时拼上随机后缀或者清理时用 API 删除。用随机数据比用固定数据 清理更省心。5. 生产级用例的可维护性规范5.1 断言写法能少写就少写要写就写 Web 优先断言Playwright 官方把expect系列断言称为Web 优先断言web-first assertion意思是这些断言会自动重试直到满足条件或超时。写用例时尽量选择带语义的断言而不是通用条件// 推荐 await expect(page.getByRole(heading, { name: 支付成功 })).toBeVisible(); await expect(locator).toHaveText(金额待确认); await expect(page).toHaveURL(/\/order\/\d/); // 不推荐不会自动重试状态没到位就挂 expect(await locator.textContent()).toBe(金额待确认);两种写法在元素已存在时结果一样但在异步渲染场景下差异巨大。前一种会自动轮询到超时后一种读到的可能是 undefined。尽量别用await locator.textContent()拿值再比对这个习惯是从 Selenium 时代带过来的在 Playwright 里没必要。5.2 偶发失败不要用 retries 掩盖但也不能不用Playwright 在配置里提供了retriesCI 上我还建议配合--shard做分片加速。但要注意retries 是止损手段不是修复手段。一条用例连续重试仍然失败说明业务逻辑或定位有问题重试次数再多也只是掩盖崩溃的时间点。我建议的用法是本地开发retries: 0失败立即暴露CI 冒烟环境retries: 2容忍偶发的网络抖动和第三方依赖波动每条用例独立配置test.describe.configure({ retries: 2 })只对会用到的文件开启配合重试一定要开trace: retain-on-failure这样重试后如果还是失败你手里一定有失败那次的完整执行录像和 DOM 快照。5.3 并行执行前先过好隔离关并行执行是 Playwright 免费送的加速能力默认项目内每条测试独立线程跑。前提是你已经按第 4 节把数据隔离做好了。如果发现并行时用例互相干扰先别急着调fullyParallel false优先检查是不是有共享文件、共享数据库状态、或同一个外部账号被同时操作。我见过最典型的并行失败多个 worker 同时登录同一个测试账号服务端把旧会话踢掉了于是用例们互相甩锅。解决办法是每个 worker 各建一个账号或用 storageState 区分。并行模式是把双刃剑隔离做得好十分钟跑完原来四十分钟的套件隔离没做好你会陷入无休止的本地过、CI 挂。6. 调试与问题排查让失败用例变成可读的证据链6.1 Trace Viewer 是排查利器Playwright 最让我惊艳的功能就是 Trace Viewer。开启 trace 后每一步操作都记录了操作前后 DOM 快照、网络请求、控制台日志、鼠标轨迹、页面截图。排查失败时不再靠猜直接看执行过程回放。推荐配置use: { trace: { mode: retain-on-failure, snapshots: true, screenshots: true, sources: true, }, }注意 trace 文件会占比较大不要全量开启后长期不清理。retain-on-failure模式只在失败时保留已经兼顾了体积和排查需求。实际排查时我一般按这个顺序看先看失败那一步的 DOM 快照元素到底长什么样再看到这一步之前最后一个成功的操作是哪一个动作导致状态变化最后看网络请求接口是否报错、是否返回了预期的数据结构。大多数 flaky 用例一小时内都能定位到根因。6.2 常见问题速查表这里整理我在项目里经常遇到的几个问题按照现象 → 原因 → 解法列个速查方便排查时对号入座现象常见原因解决方案严格模式报错定位到多个元素选择器范围太宽匹配了多个相似元素用.nth()收敛或改用getByRole name 精确定位点击超时元素不可复选元素被遮挡或处于动画中确认是否有 loading 层改用expect先等状态再操作iframe 内元素找不到selector 没指向 iframe 的定位使用frameLocator而非locator本地秒过、CI 就挂环境差异视口大小、网络、无头模式统一配置文件里的viewport、baseURL开 trace 看 CI 里到底发生了什么断言拿到 undefined直接await locator.textContent()再做比较改成await expect(locator).toHaveText(...)用例并行时互相挤掉线多个 worker 复用同一账号每个 worker 独立账号或用 storageState滚动加载后元素不在视口内元素已在 DOM 但不可交互直接操作 locatorPlaywright 会自动滚动必要时手动mouse.wheel6.3 headless 与无头模式的心得很多团队为追求速度全程用 headless 跑。这是合理的但我要提醒headless 模式下的渲染行为和真实浏览器仍有细微差异比如某些字体加载策略、动画 timing、视频自动播放策略。我见过一个用例在 headed 模式下稳定、headless 下偶发失败最后定位到是 CSS 动画的 300ms 延迟在无头环境下更明显。所以我的实践是冒烟级别的每日 CI 跑 headless 全量关键的发布前检查筛出几条核心业务链跑一次 headed 正式。不要为了追求全自动而牺牲排查成本该有人的环节就留人。7. 几个容易忽略但影响很大的细节7.1 超时时间要分场景给Playwright 默认每个操作超时 30 秒断言超时 5 秒。大多数场景够用但你可以给特殊场景单独覆盖test(大文件上传, async ({ page }) { test.setTimeout(120_000); // 整个用例超时 await page.getByTestId(upload-input).setInputFiles(big.zip, { timeout: 60_000 }); });不要图省事在配置里把全局超时调到 90 秒——全局超时拉长失败的用例要等近两分钟才报错浪费排查时间。超时越短失败反馈越快优先保证正常流程在合理时间内跑完。7.2 控制台报错和接口异常也要盯页面正常渲染不代表没有隐患。我习惯在用例前置里挂上控制台错误监听只要页面抛出pageerror或console.error就立刻记录甚至失败test.beforeEach(async ({ page }) { page.on(pageerror, err { console.error(页面 JS 异常:, err.message); }); });这一步能帮你拦截这个按钮点了没反应但不知道为什么的问题。很多时候 UI 看起来正常实际前端已经抛了异常只是被异常边界吞掉或没弹出来。把控制台日志纳入断言体系后一些偶发的前端报错会稳定暴露出来。7.3 滑块验证码、反自动化对抗这类需求正确姿势是绕开有一些团队问我怎么用 Playwright 过滑块验证码、怎么绕过站点的自动化检测。我的态度非常明确这些需求应该通过测试环境配置来解决而不是在测试代码里破解。正确做法是测试环境关闭验证码服务或配置万能验证码用 mock 拦截验证码接口返回固定通过结果验证码本身的攻防测试交给专门的安全测试工具链自动化测试的价值是验证业务逻辑的正确性不是写对抗脚本。把精力花在跟反爬机制较劲上既偏离了测试目标也让测试代码变得极其脆弱。合规、稳定、可维护的测试永远建立在干净可控的测试环境之上。7.4 测试代码也要走 Code Review测试代码也是代码一样要接受 review。我团队里有一条规矩测试用例的 PR 必须和功能代码 PR 同标准——不写注释解释为什么这么写的用例打回重写。测试用例就是项目行为的一面镜子镜子上有污渍团队对系统的认知就会有偏差。Review 时我重点看三件事定位符是否留在语义层有没有违反数据隔离原则有没有该用 web-first 断言却写了手写等待。这三条过了用例质量基本有保障。8. 最后再分享一下我踩过的坑大概一年前我在一个核心交易项目里把 Playwright 套件跑到了 300 多条用例并行 8 个 worker。那段时间最深的体会是测试的稳定性不是靠某个银弹 API 一劳永逸的而是靠一整套纪律。这里面的纪律包括定位只写语义层、数据全靠 API 准备、用例之间绝不互相依赖、trace 永远开着、失败必定位根因而不是重试过关。哪一条破了后面一定会用连续几天的 flaky 来教训你。如果你刚开始用 Playwright我给的一个最直接建议是从一个用例配齐断言、两个用例之间零共享的小目标开始练哪怕项目再小也要按这个尺度写。等这套习惯内化了你写测试的速度不只是快而且会稳得很自然。Playwright 是个好工具但真正让测试有价值的永远是你的测试设计和维护纪律。