第一次在项目里用 Playwright 替代原来的自动化方案其实没有太多复杂原因——受够了等待。之前那套 UI 测试每次跑完要喝一杯咖啡还时不时随机失败明明页面上的按钮就在那里脚本却说不存在。后来换了 Playwright整个体验完全不一样。Playwright 是一个现代浏览器自动化工具支持 Chromium、Firefox 和 WebKit一套脚本跨浏览器跑核心卖点就是自动等待、稳定的选择器和多页面场景处理。这篇文章不准备讲那些花里胡哨的理论就围绕“从零开始”这四个字把从安装到落地到 CI 的过程里的经验、坑和思路盘出来。不管你是刚接触 UI 自动化测试的新手还是被老框架折磨过想换工具的老手下面这些内容基本都能直接用。1. 为什么是 PlaywrightUI 自动化测试的选型思考1.1 从老牌框架到 Playwright我为什么换工具先说结论不是老牌框架不行而是 Playwright 更符合现代 Web 应用的测试方式。老牌框架的做法是“模拟用户在页面上操作”这本身没问题但实现上有个拧巴的地方——它需要显式地等待元素出现否则就会报错。于是测试代码里全是sleep(2)、sleep(5)这种玄学等待。为什么是 2 秒而不是 3 秒没人说得清只能靠试。网络慢一点页面加载超过 2 秒脚本直接挂网络快了2 秒又白白浪费整个测试跑下来一半时间在闭眼等。Playwright 的设计思路是“浏览器自己在等”。它监听浏览器事件只有当元素可交互、网络请求完成、页面稳定之后才会继续执行下一步。换句话说它把“等一下”这件事从测试代码里解放出来了。我接手过一个老项目里面 UI 脚本大量使用固定等待和脆弱的选择器迁移到 Playwright 后同样的场景脚本行数少了一半运行时间少了将近四成最关键的是——不会因为机器偶尔卡顿就随机失败了。1.2 Playwright 的核心设计理念一个浏览器实例搞定一切Playwright 的底层是浏览器厂商自己维护的调试协议它跟浏览器绑定得很紧。Kubernetes 那种“容器编排”的类比可能有点远更形象一点说它就是直接“驾驶”浏览器而不是在浏览器外面“按键”。最典型的体现就是它的上下文Context机制。Playwright 里浏览器实例可以开出多个独立的 Context你可以理解成一个个“隔离的房间”。每个 Context 都有自己的缓存、Cookie、存储甚至不同的代理和权限。这个设计对测试非常友好你可以在同一个浏览器进程里并行跑多个测试用例互不干扰不用反复启动浏览器想在已登录状态下做一套操作、在未登录状态下做另一套直接用 Context 复制就能搞定。这在老框架里需要手动处理 Cookie 和本地存储麻烦得很。另一个理念是“在真实浏览器条件下工作”。Playwright 强调移动视口模拟、地理位置模拟、权限授予这些不是花架子。移动端专项测试之前总要接真机或单独配置模拟器现在用 Playwright 的device描述符一条playwright.devices[iPhone 13]就能模拟出对应的浏览器特征。1.3 适用场景与不适用场景没有银弹Playwright 也有自己的边界。先说我推荐用它做的事Web 端 UI 回归测试特别是核心业务链路比如登录、下单、支付流程。跨浏览器兼容性验证同一套脚本在 Chromium、Firefox、WebKit 上跑一遍比手动开三个浏览器快得多。接口与页面混合测试可以在 UI 操作的同时拦截或 mock 接口数据。页面性能相关的基础验证测量关键步骤的耗时、记录网络请求次数等。不太适合做的场景桌面客户端软件如 Electron 以外的原生应用自动化Playwright 管不了。需要真正移动端 App 内环境原生控件的测试应该用移动端专项工具。纯单元测试那是单测框架的领域UI 自动化测试的成本高得多没有必要。一句话它是端到端测试工具不是万能的测试平台。把合适的工作交给合适的工具这才是工程化思考的起点。2. 环境准备与第一个脚本5 分钟跑通最小闭环2.1 安装与依赖配置安装 Playwright 比想象中简单前提是 Python 环境干净。我建议用虚拟环境避免依赖冲突。下面这四条命令是基础python -m venv mytestenv source mytestenv/bin/activate # Windows 下用 mytestenv\Scripts\activate pip install pytest-playwright playwright install这里有一个关键点playwright install不是安装 Python 包而是下载浏览器内核。它默认会装 Chromium、Firefox 和 WebKit 三套。如果只是为了快速验证可以只装 Chromium省时间也省硬盘playwright install chromium基于常见实践的补充在团队协作时建议把 Playwright 版本和浏览器版本都锁死。最简单的办法是在项目根目录放一个 requirements.txt里面固定版本号同时把playwright install的缓存目录纳入 CI 缓存策略。不然队友电脑装的浏览器内核版本不一致测试结果会出现莫名的差异。2.2 第一个自动化脚本打开网页、点击、断言新建一个test_demo.py内容如下from playwright.sync_api import sync_playwright def test_first(): with sync_playwright() as p: browser p.chromium.launch(headlessFalse) page browser.new_page() page.goto(https://example.com) page.fill(#username, testuser) page.click(button:has-text(登录)) page.wait_for_selector(text欢迎回来) print(登录成功) browser.close()如果你对 pytest 比较熟建议直接用官方推荐的写法from playwright.sync_api import Page def test_login(page: Page): page.goto(https://example.com) page.fill(#username, testuser) page.click(button:has-text(登录)) page.get_by_text(欢迎回来).click()注意第二个脚本里没有browser和context因为 pytest-playwright 插件帮你管理了这些生命周期。测试函数直接拿一个page对象用就行这是最省心的方式。运行命令是pytest test_demo.py --headed--headed表示有头模式能看到浏览器被操作的过程不加就默认无头。2.3 同步模式还是异步模式新手怎么选Playwright 提供两套 APIsync_api和async_api。我用过两种说下感受。同步模式代码顺序执行不用思考“回调”和“等待”对新手特别友好调试也容易。pytest 生态默认使用同步 API99% 的测试场景都能满足。异步模式适合在异步框架如 FastAPI、asyncio 项目里集成或者在同一个进程里需要更高并发的时候。但异步代码一旦报错堆栈信息比较绕新手容易迷失。我的建议是除非你明确知道自己需要异步否则先学同步模式。不仅容易上手后期看文档、抄插件也基本遇不到额外门槛。等把同步模式跑熟了再去理解异步的价值也不迟。3. 核心 API 拆解选择器、等待与断言避免脆弱的脚本3.1 选择器策略为什么推荐 user-facing 选择器UI 自动化测试最痛的一点就是“页面没变测试挂了”。最常见的元凶是前端把id改了、把 CSS 类名换了而测试脚本还在用#old-id找元素。Playwright 提供了一套以用户视角定位元素的方式官方叫 user-facing selector我体验下来非常实用。几个典型写法# 根据文本定位按钮 page.get_by_text(确认付款) # 根据角色和名字定位 page.get_by_role(button, name提交订单) # 根据占位符定位输入框 page.get_by_placeholder(请输入邮箱) # 根据标签关联定位 page.get_by_label(用户名)为什么推荐这些因为它们贴近真实用户的操作方式。用户不会关心按钮的 id 是什么用户只关心“这个按钮写的是提交订单”。get_by_role(button, name提交订单)这种写法即使前端重构了 CSS只要按钮文本和角色不变测试就依然有效。不如再解释一下 role 选择器的好处它能同时校验可访问性Accessibility。如果一个按钮只靠图片展示、没有文字也没有 aria-labelget_by_role会找不到这恰恰暴露了页面无障碍设计的问题。所以它既是定位器也是一个隐性的可访问性测试器。选择器的优先级我个人的默认顺序是用户可见的文本、角色、标签通过>page.set_default_timeout(10000) # 默认等待10秒单位毫秒但请不要一遇到超时就盲目调大全局等待。更好的方式是针对某个慢接口单独等待page.wait_for_response(lambda response: api/order/status in response.url, timeout15000)如果确实需要对某个不稳定元素额外等待可以这样page.get_by_text(加载完成).wait_for(statevisible, timeout8000)关键点自动化测试最大的敌人不是慢而是不确定。固定 sleep 是不确定乱调超时也是不确定。我们要做的是针对“真正需要等待的事件”设置合理的超时而不是用 sleep 把整个流程拖慢。3.3 断言库expect vs 传统断言Playwright 自带一套断言库和 pytest 的assert相比最大的优势是“自动重试”。什么意思就是你断言一个元素不可见如果立刻检查可能动画刚启动元素还在Playwright 的expect会反复尝试直到超时或通过。看个例子from playwright.sync_api import expect expect(page.get_by_text(订单已提交)).to_be_visible() expect(page.locator(.error)).to_have_count(0) expect(page.get_by_role(button, name提交)).to_be_disabled()这些断言默认会轮询检查轮询间隔是 100ms直到达到超时时间。这解决了一个老生常谈的问题页面动画结束前就去检查状态然后测试失败。用expect后断言自带“缓冲区”脚本稳定很多。传统断言不是不能用它适合纯逻辑判断比如比较变量assert order_id expected_id但凡是涉及 DOM 状态、元素数量、可见性、文本内容的断言我都推荐用expect。两者配合逻辑归逻辑页面归页面井水不犯河水。4. 进阶技能网络拦截、多页面与视觉验证4.1 拦截网络请求与模拟接口UI 自动化测试最烦的就是环境不稳定。第三方支付接口超时、验证码服务抽风、推荐接口返回大流量数据导致页面卡死。Playwright 可以在网络层做手脚让测试不受外部环境干扰。拦截请求的方式有几种# 直接中止某种类型的请求 page.route(**/*.png, lambda route: route.abort()) # 篡改响应数据mock接口返回 def mock_api(route): route.fulfill(status200, content_typeapplication/json, body{code: 0, data: []}) page.route(**/api/recommend**, mock_api) # 继续放行但可以做日志记录 page.route(**/*.js, lambda route: route.continue_())实际项目里最常用的场景是 mock 登录接口和支付回调。我做过一个电商项目支付环节接了真实沙箱环境每次在沙箱里等回调要十几秒而且偶尔不稳定。后来用page.route拦截支付回调接口直接伪造一个“支付成功”的响应整个下单流程测试从 30 秒缩短到 8 秒且稳定率达到 99% 以上。当然这并不意味着完全抛弃真实环境——冒烟测试用 mock上线前再跑一次完整真实链路两不误。还有更细的玩法通过page.on(request)监听请求可以统计某个按钮点击后发出了哪些请求用来做数据埋点验证。这在老框架里是做不到的因为浏览器事件没有暴露到协议层。4.2 多标签页和 iframe 处理现代 Web 应用里经常出现新窗口、弹窗、iframe 嵌入的场景。Playwright 处理这些比老框架顺手得多。新标签页弹窗的处理关键是等待context上出现新的pagewith context.expect_page() as new_page_info: page.click(a[target_blank]) new_page new_page_info.value new_page.wait_for_load_state() print(new_page.title())因为expect_page这个上下文管理器会等待弹窗事件然后把新页面对象交给你不需要再费劲从context.pages里猜。iframe 就更简单了直接通过frame_locator定位page.frame_locator(#mainIframe).get_by_role(button, name提交).click()要注意如果 iframe 的内容是跨域的脚本也能操作因为 Playwright 走的是浏览器协议层不受同源策略限制。这一点和老框架里经常遇到的桥接问题完全不同实测下来非常爽。4.3 截图、录屏与视觉对比调试 UI 测试时最宝贵的是“证据”。Playwright 的截图和录屏是内置的# 元素截图 page.get_by_role(button, name提交).screenshot(pathbutton.png) # 整页截图 page.screenshot(pathfull.png, full_pageTrue) # 失败时自动截图通过trace page.tracing.start(screenshotsTrue, snapshotsTrue) # 执行测试 page.tracing.stop(pathtrace.zip)录屏功能主要在 trace viewer 里用常见做法是在 conftest 里加一个 hook测试失败时自动开启 tracepytest.hookimpl(tryfirstTrue) def pytest_runtest_makereport(item, call): if call.when call and call.excinfo is not None: page: Page item.funcargs.get(page) if page: page.screenshot(pathffailure_{item.name}.png)不仅仅是为了“留证据”截图还有一个作用视觉回归测试。你可以把两张截图做像素级差异对比识别页面布局是否意外变化。官方的expect(page).to_have_screenshot()就支持这个能力我通常在关键页面首页、详情页、盲盒支付页都加上这个断言。但要注意视觉断言对渲染环境特别敏感字体、系统缩放、显卡驱动都可能造成像素差异。如果你要在 CI 里做视觉回归尽量使用统一的容器镜像固定浏览器的版本并且设一个合理的阈值。否则每天都会收到一堆像素级差异的误报最后团队会直接把这条断言禁掉那就失去意义了。5. 工程化落地从脚本到可维护的测试套件5.1 测试组织与夹具Fixture单条脚本不是自动化测试一个可维护的测试套件才是。Playwright 的 fixture 机制是我最推崇的工程化能力。它不只是“setup 和 teardown 的封装”更像是一个依赖注入体系。举一个真实例子我维护一套后台管理系统的测试所有用例需要先登录、再进入不同菜单。最土的做法是每条用例都复制登录步骤后果就是登录流程一改几十条用例一起改。用 fixture 就是另一番光景import pytest from playwright.sync_api import Page, BrowserContext pytest.fixture def logged_in_page(page: Page): page.goto(/login) page.fill(#username, admin) page.fill(#password, ***) page.click(button:has-text(登录)) page.wait_for_selector(text工作台) yield page page.context.clear_cookies()测试函数直接写成def test_order_list(logged_in_page): logged_in_page.get_by_text(订单管理).click() expect(logged_in_page.get_by_role(table)).to_be_visible()后续登录逻辑变化改 fixture 一个地方就够了。而且 fixture 可以有依赖关系logged_in_page依赖page你还可以创建db_connection依赖logged_in_page层层注入结构清晰。还有一点fixture 的作用域scope控制很关键。默认是函数级每个用例都重新登录。如果登录本身耗时较长可以设置scopesession多个测试共享登录态。但这会牺牲隔离性——某个用例改了用户状态后面用例会受影响。我的建议是核心业务流保持函数级非破坏性的只读用例可以放宽到模块级。5.2 配置浏览器、超时、重试真实的测试项目不会只用一个浏览器跑一遍就完事。工程化配置主要做三件事多浏览器矩阵、统一的超时与重试策略、合理的并发策略。pytest-playwright支持参数化浏览器pytest test_demo.py --browser chromium --browser firefox --browser webkit这样一套脚本就跑了三个浏览器。代价是测试时间三倍但换来了跨浏览器信心。日常开发用 chromium 快速验证提交前或夜间跑全矩阵效率更高。超时配置我建议统一写在配置或 fixture 里pytest.fixture def page(page: Page): page.set_default_timeout(15000) yield page重试策略我一般分两层pytest 层设置--reruns2配合 pytest-rerunfailures 插件Playwright 操作层不建议每条操作都重试因为操作层自动重试可能导致状态错乱比如已经点了“提交”又自动点一次就重复提交了。所以重试尽量在“用例”这一层而不要在“操作”这一层。并发策略上用 pytest-xdist 的-n auto可以并行跑测试但要注意每个 worker 消耗一个浏览器实例。CI 机器的 CPU 和内存要留足否则并行反而更慢。我曾经在 2 核 4G 的 CI 机器上开 8 个 worker结果浏览器全部卡死后来调成 4 个 worker 才稳定。5.3 与 CI/CD 集成让测试自动跑起来UI 自动化测试最大的价值在于持续回归。我提供一个经过多次迭代后比较稳的最小 CI 配置以通用流水线语言为例stages: - test test: stage: test image: mcr.microsoft.com/playwright:v1.35.0-focal before_script: - pip install -r requirements.txt script: - pytest tests/ --browser chromium --browser firefox --maxfail3 --htmlreport.html artifacts: when: always paths: - report.html - test-results/ expire_in: 7 days retry: max: 2 when: - runner_system_failure - stuck_or_timeout - unknown_failure几点经验官方提供的 Playwright Docker 镜像里已经预装好浏览器及其系统依赖别自己在裸容器里现装坑非常多。测试报告保留时间不用太长7 天足够排查问题。CI 里跑还是尽量无头模式不要--headed否则容易因为缺少显示服务器而死掉。失败用例的重试放在流水线层级效果比在测试代码里写循环好得多。还有一件事我一开始忽略了CI 里跑 UI 测试网络出口一定要稳定。曾经因为某个第三方 CDN 在 CI 环境下被限速导致page.goto超时后来把测试中不需要的外部站点请求全部 route 掉才算根治。这也是为什么前面第 4.1 节说的网络拦截能力在 CI 环境里几乎是必备技能。6. 常见问题与排查技巧实录6.1 元素找不到、超时、慢怎么排查几乎所有新手都会遇到“元素找不到”的报错。我看到最多的信息是TimeoutError: Timeout 3000ms exceeded.对待这个报错我的排查顺序是固定的看浏览器当前页面是否符合预期。用page.screenshot(pathdebug.png, full_pageTrue)先截图眼见为实。确认元素是否在 iframe、Shadow DOM 内部。这两种场景是定位失败的常客。确认选择器是否准确。在断点处调用page.locator(your-selector).count()看看匹配数量是 0 还是大于 1。大于 1 说明定位不唯一需要收紧条件。检查是否被风控或弹窗拦截。很多系统会在无人值守时弹出消息框、广告位挡住了真正的按钮。检查是否有懒加载。页面滚动后才加载的元素需要先滚动到目标位置。这里再给一个调试神器——生成实时定位测试代码page.pause()在脚本里加上这一行跑起来会打开 Playwright Inspector可以边看页面边实时尝试选择器找到合适的就自动生成代码。这个工具比打印日志高效十倍。6.2 动态渲染与前端框架的坑现代前端框架Vue、React会让 DOM 频繁更新如果测试脚本里的操作节奏比页面的协同轮还快就容易出现奇怪的问题。典型场景列表加载中显示“骨架屏”内容还没渲染完脚本就往下走了。点击按钮后按钮进入 loading 状态但依然可点重复触发了两次请求。输入框编辑器如富文本初始化慢fill 之后又被编辑器自动清空了。对策主要有三个第一优先依赖 Playwright 的自动等待让操作等待元素可交互。但注意“可交互”不等于“内容正确”。如果页面显示了旧数据你等到的可能只是旧的稳定状态。这种情况需要用expect去断言特定文本出现。第二用wait_for_function做自定义等待。比如富文本里需要等待特定文本写入page.wait_for_function(document.querySelector(.editor).innerText.includes(目标内容))第三触发事件后不要立刻断言而用expect的自动重试。只要不是秒级超时都能扛过前端状态切换的过渡期。踩过一次比较深的坑某表单页面使用了 Vue 的 v-model脚本通过page.fill填入内容后发现页面上的校验提示一直不消失。后来发现是fill()触发了 input 事件但 Vue 依赖 change 事件同步 v-model于是字段值始终没更新。解决方案是 fill 之后再执行一次page.locator(input).press(Tab)让输入框失焦触发 change 事件。这类问题没有通用解遇到后查一下框架的事件机制比瞎试快得多。6.3 小白避坑清单五个高频失误最后梳理一下我见过最多的五个失误每个都是真实教训失误一测试依赖外部数据而不做前置准备。UI 测试最需要稳定的数据。建议每个用例自带数据准备和清理逻辑用接口创建测试数据不要偷偷依赖上一条用例留下的脏数据。失误二断言写得太粗只验“按钮被点了”。测试的价值在于验证业务正确性不是验证“操作发生了”。应该断言后续结果是否存在比如页面跳转、数据变化、请求发出。失误三无脑用sleep。这条必须强调一遍看到sleep就要警惕它可能掩盖了真正的同步问题。用自动等待或者等待事件替代。失误四测试用例之间共享可变全局状态。比如某个用例修改了 localStorage另一个用例读出来不对。解决办法就是用 Context 隔离或者显式地清理状态。失误五把超时时间调到极大。设 30 秒甚至 60 秒确实能解决超时但会让失败用例磨蹭很久。更合理的做法是保留 5~10 秒默认超时针对特别慢的稳定接口单独延长配合网络拦截减少等待。对比速查表场景推荐做法错误做法等待元素出现使用 expect 自动重试固定 sleep(3)定位按钮get_by_role / get_by_text一长串 XPath断言状态expect().to_be_visible()直接 assert 元素句柄处理弹窗expect_page 上下文硬取 page 列表数据准备接口造数 fixture 清理测试依赖测试这些小坑不致命但叠加在一起就会让人产生“UI 测试天生不稳定”的错觉。工具是死的用工具的人是活的。把根因找出来大多数“随机失败”根本没有什么随机性只是等待策略和定位策略没做对。最后再分享一个小技巧不管项目大小强烈建议在本地跑通一遍 Playwright 的 Trace Viewer失败用例自动生成 trace 文件直接打开可以看到完整的界面快照、网络请求、控制台日志和操作时间线。排查问题时别人还在猜你已经在看回放效率完全是两个级别。这套流程我已经用了很久从脚本编写到 CI 排障基本离不开它。