1. 为什么我最终把自动化测试的主力工具换成了 Playwright做自动化测试这些年我踩过的坑不算少。早期用 Selenium 写脚本最头疼的就是等元素加载——明明页面上已经能看到按钮了脚本就是点不到报一堆ElementNotInteractableException。后来加了一堆time.sleep脚本跑得比蜗牛还慢还经常在 CI 上翻车。直到我开始认真用 Playwright才发现原来浏览器自动化可以这么省心。Playwright 是微软开源的一个浏览器自动化框架支持 Chromium、Firefox、WebKit 三大内核提供 Python、JavaScript/TypeScript、Java、.NET 多语言绑定。它能做什么简单说凡是你在浏览器里手动能做的事——点击、输入、滚动、截图、拦截网络请求、监听接口返回——它都能用代码自动完成。适合谁学测试工程师、爬虫开发者、需要做页面监控的运维、想给 Web 项目加端到端测试的前端甚至产品经理拿它做重复性页面操作都很合适。这篇文章我不打算写成官方文档的中文翻译那种东西你翻文档就够了。我想做的是把 Playwright 从安装到写出一个能跑、能维护、能上 CI 的测试脚本这条完整链路拆开把每一步背后的“为什么”讲清楚再把我实际踩过的坑和总结的技巧一并倒出来。你跟着走一遍基本就能独立上手了。2. 环境搭建与工具选型别一上来就装错版本2.1 Python 环境准备与虚拟环境隔离Playwright 的 Python 版本对解释器有要求官方建议 Python 3.8 及以上。我实测下来3.9 到 3.12 都比较稳3.13 早期版本偶尔会有依赖编译问题建议避开刚发布的大版本。安装 Python 本身没什么好说的官网下载安装包Windows 记得勾选“Add Python to PATH”这一步漏了后面命令行找不到 python 会折腾半天。真正要强调的是虚拟环境。很多人图省事直接全局pip install playwright结果项目 A 需要旧版本、项目 B 需要新版本互相打架。我的习惯是每个项目一个 venvpython -m venv venv # Windows venv\Scripts\activate # macOS / Linux source venv/bin/activate激活后命令行前面会出现(venv)标识这时候再装包所有依赖都锁在这个项目里。这个习惯看起来多一步但能帮你省掉未来无数次“为什么我本地能跑 CI 跑不了”的排查时间。2.2 Playwright 安装与浏览器驱动下载装 Playwright 本体只要一行pip install playwright但注意这只是装了 Python 库浏览器内核还没下载。很多人装完直接跑脚本报“Executable doesnt exist”就是漏了下一步playwright install这条命令会下载 Chromium、Firefox、WebKit 三个内核加起来几百 MB国内网络环境下可能比较慢。如果只需要 Chromium可以只装一个playwright install chromium这里有个经验点Playwright 的浏览器驱动是它自己维护的定制版本跟你系统里装的 Chrome 不是一回事。它不依赖你本地的谷歌浏览器驱动也不需要你手动配置 chromedriver 路径——这正是它比 Selenium 省心的地方之一。Selenium 要你下载对应版本的 chromedriver 并保证版本匹配版本对不上直接报错Playwright 把浏览器和驱动打包在一起管理playwright install一步到位。提示如果公司网络有代理限制导致下载失败可以设置环境变量PLAYWRIGHT_DOWNLOAD_HOST指向内部镜像源具体地址问你们运维。2.3 编辑器与调试工具的选择写 Playwright 脚本我推荐 VS Code 加 Python 插件配合 Playwright 官方的 VS Code 扩展体验更好。这个扩展能直接在编辑器里跑测试、看 trace、定位元素比纯命令行调试效率高不少。另外强烈推荐一个工具playwright codegen。这是 Playwright 自带的代码生成器运行playwright codegen https://example.com它会打开一个浏览器窗口你在里面怎么操作它就实时生成对应的 Python 代码。对于不熟悉元素定位语法的新手这是最快的入门方式——先录一遍再照着生成的代码改。我到现在遇到复杂交互还是会先用 codegen 录一遍看看官方推荐的写法。3. 核心概念拆解Browser、Context、Page 三层结构3.1 三层结构到底是什么关系Playwright 的 API 设计里最核心的是三层对象Browser、BrowserContext、Page。很多人初学时会混淆我用一个生活化的类比解释Browser相当于你电脑上打开的一个浏览器程序比如双击 Chrome 图标启动的那个进程。BrowserContext相当于浏览器里的一个“隐身窗口”或独立用户会话它有自己的 cookie、localStorage、缓存和其他 context 完全隔离。Page相当于这个窗口里的一个标签页。为什么要有 Context 这一层因为测试隔离。如果你用同一个 Browser 直接开多个 Page它们共享 cookie 和登录状态测试之间会互相污染。而每个测试用一个独立的 Context就相当于每个测试都在一个全新的、干净的浏览器环境里跑互不影响。这是 Playwright 相比 Selenium 在架构上的一个重要优势。from playwright.sync_api import sync_playwright with sync_playwright() as p: browser p.chromium.launch(headlessFalse) context browser.new_context() page context.new_page() page.goto(https://example.com) print(page.title()) browser.close()这段代码就是最基础的三层结构演示。headlessFalse表示显示浏览器界面调试时很有用上线跑 CI 时改成True或无头模式速度更快。3.2 同步 API 与异步 API 怎么选Playwright 的 Python 版同时提供同步sync和异步async两套 API。同步 API 写起来直观适合大多数测试场景异步 API 适合需要高并发、同时操作多个页面的场景比如批量爬取。我的建议是测试脚本优先用同步 API因为测试逻辑本身是线性的同步写法可读性更好调试也简单。只有当你需要同时开几十个页面并发抓数据时才考虑异步。不要为了“显得高级”硬上 async结果被事件循环和 await 搞得头大。3.3 自动等待机制Playwright 最值钱的功能如果只能让我夸 Playwright 一个功能我选自动等待auto-waiting。Selenium 时代元素没加载出来就操作会直接报错你得手动写WebDriverWait或者time.sleep。Playwright 在执行每个操作前会自动等待元素满足可操作性条件可见、稳定、可接收事件、没有被其他元素遮挡。这意味着你写page.click(#submit)时不需要在它前面加任何等待代码。Playwright 会自己判断这个按钮什么时候能点超时了才报错。默认超时是 30 秒可以通过page.set_default_timeout()调整。这个机制背后是 Playwright 通过浏览器协议持续监听 DOM 状态变化而不是像 Selenium 那样轮询。所以它既快又准不会出现“等够了时间但元素还没出来”或者“元素早出来了却白等 5 秒”的情况。4. 元素定位实战八种定位方式与优先级4.1 推荐的定位器优先级元素定位是自动化测试的基本功定位器写得好脚本稳定性直接翻倍。Playwright 提供了多种定位方式我按推荐优先级排个序get_by_role基于 ARIA 角色定位最贴近用户视角最稳定get_by_label / get_by_placeholder表单元素首选get_by_text基于可见文本直观但要注意文本可能变化get_by_test_id基于专门的测试属性最可控locator(css...)CSS 选择器灵活但依赖页面结构locator(xpath...)XPath功能强但可读性差、易碎为什么把 role 放第一位因为它基于无障碍语义一个按钮不管它的 class 怎么变、位置怎么挪它的 role 始终是 buttonname 始终是它的文本。这种定位器对页面改版有很强的免疫力。# 推荐写法 page.get_by_role(button, name登录).click() page.get_by_label(用户名).fill(testuser) page.get_by_placeholder(请输入密码).fill(password123) # 次选写法 page.locator(#login-btn).click() page.locator(css.form-input nth0).fill(testuser)4.2 定位器严格模式与多元素处理Playwright 默认开启严格模式strict mode如果一个定位器匹配到多个元素操作时会直接报错而不是默默选第一个。这个设计是为了防止你误操作到错误的元素。比如页面上有多个“删除”按钮你写page.get_by_text(删除).click()就会报错。解决办法有两种一是用.first、.nth(1)明确指定二是把定位器写得更精确缩小范围。# 明确指定第一个 page.get_by_text(删除).first.click() # 缩小范围先定位到某一行再在该行内找按钮 row page.locator(tr).filter(has_text张三) row.get_by_role(button, name删除).click()第二种写法是我更推荐的因为它表达了你真实的意图——“删除张三这一行的按钮”而不是“页面上第一个删除按钮”。意图清晰脚本才稳定。4.3 定位器链式操作与过滤Playwright 的 locator 支持链式调用和过滤这是它比 Selenium 优雅很多的地方。你可以像写查询语句一样层层筛选# 在列表中找到包含特定文本的项再点它里面的链接 page.locator(.product-list) .locator(.product-item) .filter(has_textiPhone) .get_by_role(link, name详情) .click()filter还支持has和has_not参数可以按子元素存在与否过滤。这套组合拳用熟了再复杂的页面结构都能精准定位而且代码读起来像自然语言。注意不要过度依赖nth()这种按索引定位的写法。索引会随页面数据变化而失效今天第 3 个元素是你要的明天数据一变就错了。优先用文本、属性等语义化条件。5. 完整实操从零写一个可维护的登录测试5.1 项目结构设计先别急着写代码项目结构定好了后面维护省一半力气。我常用的结构是这样的project/ ├── pages/ │ ├── __init__.py │ ├── base_page.py │ └── login_page.py ├── tests/ │ ├── __init__.py │ └── test_login.py ├── conftest.py ├── pytest.ini └── requirements.txt这是典型的 Page Object Model页面对象模型结构。核心思想是把“页面元素定位”和“测试逻辑”分开页面对象负责“这个页面上有什么元素、怎么操作”测试用例负责“我要验证什么业务逻辑”。页面改版时你只改页面对象测试用例不用动。5.2 页面对象封装先写一个基础页面类把公共操作抽出来# pages/base_page.py from playwright.sync_api import Page class BasePage: def __init__(self, page: Page): self.page page def goto(self, url: str): self.page.goto(url) return self def get_title(self) - str: return self.page.title() def wait_for_load(self): self.page.wait_for_load_state(networkidle)再写登录页面对象# pages/login_page.py from playwright.sync_api import Page, expect from .base_page import BasePage class LoginPage(BasePage): URL https://example.com/login def __init__(self, page: Page): super().__init__(page) self.username_input page.get_by_label(用户名) self.password_input page.get_by_label(密码) self.login_button page.get_by_role(button, name登录) self.error_message page.locator(.error-msg) def open(self): self.goto(self.URL) return self def login(self, username: str, password: str): self.username_input.fill(username) self.password_input.fill(password) self.login_button.click() return self def expect_login_success(self): expect(self.page).to_have_url(lambda url: dashboard in url)注意expect的用法。Playwright 内置了断言库它会自动重试直到条件满足或超时比手写assert加等待靠谱得多。to_have_url传一个 lambda 做模糊匹配比精确匹配整个 URL 更健壮。5.3 测试用例编写与 pytest 集成Playwright 和 pytest 是绝配。用 pytest 的 fixture 管理浏览器生命周期用参数化跑多组数据# conftest.py import pytest from playwright.sync_api import sync_playwright pytest.fixture(scopesession) def browser(): with sync_playwright() as p: browser p.chromium.launch(headlessTrue) yield browser browser.close() pytest.fixture def page(browser): context browser.new_context() page context.new_page() yield page context.close()这里browser用 session 级别整个测试会话只启动一次浏览器省时间page用 function 级别每个测试用例一个全新 context保证隔离。这个组合是我实测下来速度和隔离性平衡得最好的方案。测试用例# tests/test_login.py import pytest from pages.login_page import LoginPage def test_login_success(page): login_page LoginPage(page).open() login_page.login(testuser, correct_password) login_page.expect_login_success() pytest.mark.parametrize(username,password,error, [ (, pass, 用户名不能为空), (user, , 密码不能为空), (user, wrong, 用户名或密码错误), ]) def test_login_failure(page, username, password, error): login_page LoginPage(page).open() login_page.login(username, password) expect(login_page.error_message).to_contain_text(error)参数化那一段三组异常数据一次跑完比写三个几乎一样的测试函数清爽多了。这也是 pytest 相比 unittest 的优势。5.4 运行测试与查看报告跑测试pytest tests/ -v想要更详细的执行报告加--tracingon参数Playwright 会记录完整的执行轨迹包括每一步的截图、DOM 快照、网络请求。测试失败后运行playwright show-trace trace.zip会打开一个可视化界面你能像看录像一样回放整个测试过程精确定位到哪一步出了问题。这个功能排查 CI 上的偶发失败特别有用——本地复现不了的 bug看 trace 一目了然。6. 进阶技巧网络拦截、请求监听与多标签页6.1 监听和修改网络请求Playwright 能拦截页面发出的所有网络请求这在测试中用途很大。比如你想验证某个接口被调用了、想 mock 接口返回、想加速测试跳过图片加载# 监听所有请求 page.on(request, lambda req: print(f {req.method} {req.url})) # 监听响应 page.on(response, lambda res: print(f {res.status} {res.url})) # 拦截并修改响应 def handle_route(route): if /api/user in route.request.url: route.fulfill( status200, content_typeapplication/json, body{name: mocked_user} ) else: route.continue_() page.route(**/*, handle_route)route.fulfill直接返回伪造数据route.continue_()放行正常请求。用这个技巧你可以在不依赖后端的情况下测试前端逻辑或者模拟各种异常返回500、超时、空数据来验证页面的容错处理。6.2 处理 iframe 和动态内容iframe 是自动化测试的老大难。Playwright 处理 iframe 用的是frame_locator语法和普通 locator 一致frame page.frame_locator(#my-iframe) frame.get_by_role(button, name确认).click()对于动态加载的内容不要用wait_for_timeout硬等用wait_for_selector或直接依赖自动等待# 等某个元素出现 page.wait_for_selector(.data-loaded, statevisible) # 等网络空闲 page.wait_for_load_state(networkidle)networkidle表示 500ms 内没有新的网络请求适合等待 AJAX 加载完成。但要注意如果页面有轮询请求networkidle可能永远等不到这时候改用wait_for_selector更靠谱。6.3 多标签页与弹窗处理点击链接打开新标签页是常见场景Playwright 用expect_page上下文管理器处理with page.context.expect_page() as new_page_info: page.get_by_role(link, name打开新窗口).click() new_page new_page_info.value new_page.wait_for_load_state() print(new_page.title())弹窗alert、confirm用事件监听page.on(dialog, lambda dialog: dialog.accept()) page.get_by_role(button, name删除).click()dialog.accept()相当于点“确定”dialog.dismiss()相当于点“取消”。如果弹窗需要输入文本用dialog.accept(输入的文本)。7. 常见问题与排查技巧实录7.1 高频报错速查表报错信息常见原因解决思路Timeout exceeded元素未出现或不可操作检查定位器是否正确用 codegen 验证确认是否需要先登录Strict mode violation定位器匹配到多个元素用 .first/.nth 或 filter 缩小范围Executable doesnt exist浏览器内核未安装运行 playwright installElement is not visible元素被隐藏或遮挡检查 CSS 显示状态滚动到元素位置Target closed页面或浏览器已关闭检查是否提前调用了 close或页面崩溃7.2 定位器调试的独家技巧定位器写不对是新手最常见的卡点。我有个屡试不爽的调试方法在脚本里临时加一句page.pause()它会暂停执行并打开 Playwright Inspector你可以在里面实时测试定位器、查看元素高亮。比反复改代码跑脚本快得多。另一个技巧是用count()先确认匹配数量print(page.get_by_role(button).count())如果输出是 0说明定位器没匹配到如果是 5说明匹配太多需要缩小范围。先确认数量再操作能避免很多盲目试错。7.3 提升脚本稳定性的经验总结跑了这么多项目我总结出几条让脚本更稳的原则优先用语义化定位器少用 CSS 和 XPath 依赖页面结构不要用固定 sleep依赖自动等待和显式等待条件每个测试独立 context避免状态污染断言用 expect 而非 assert享受自动重试失败时看 trace不要靠猜还有一点容易被忽略测试数据要可控。如果测试依赖数据库里的某条数据而这条数据被别的测试改了你的测试就会莫名其妙失败。解决办法是每个测试自己准备数据、自己清理或者用接口 mock 隔离外部依赖。提示CI 环境跑测试时建议开启--tracingretain-on-failure只在失败时保留 trace既省存储又方便排查。8. 关于 Playwright 与 AI 结合的一些实践体会最近自动化测试圈子里 AI 结合是个热话题我也试了一些方向。比较实用的一个是用大模型辅助生成定位器把页面 HTML 片段丢给模型让它推荐稳定的定位策略比人工翻 DOM 快。另一个方向是用自然语言描述测试步骤让模型翻译成 Playwright 代码适合快速搭原型。但我要泼盆冷水AI 生成的测试代码目前还不能直接上生产。它经常写出依赖脆弱定位器、缺少断言、没有异常处理的代码。我的做法是把 AI 当“高级代码补全”用——让它生成初稿我再按前面讲的规范重构。真正决定测试质量的还是你对页面结构的理解和对业务逻辑的把握这部分 AI 暂时替代不了。Playwright 本身也在往智能化方向走比如 codegen 已经能生成比较规范的代码未来可能会有更强的自愈定位能力。但工具再智能测试的思维——怎么设计用例、怎么保证隔离、怎么定位问题——还是得靠人来沉淀。这也是我写这篇东西的初衷工具会更新方法论才是能带走的东西。