最近项目里要把一批老接口的回归测试捡起来，看了好几个自动化方案，最后选定 Playwright 作为主力工具，断断续续用了一个多月，踩了不少坑，也积累了不少经验。这篇笔记是 Day 01 的基础内容，先把原理讲明白，再把最常用的基础操作过一遍。适合刚接触 Playwright、之前主要用 Selenium 或 Requests 做网页自动化的人看，也适合想系统理清这套工具设计逻辑的读者。
我尽量不写成文档翻译，而是用一个用过的角度，把“为什么这么设计”“实操时哪里容易翻车”都讲清楚。
1. 为什么要用 Playwright：核心原理与架构思路
1.1 从“脚本能跑”到“稳定能复用”的痛点
我先说个背景。之前用 Selenium 做 Web 自动化遇到最多的三个问题：浏览器驱动版本频繁失配、页面加载慢导致脚本不稳定、以及多窗口多页面管理起来特别别扭。每次换台机器或者 CI 环境重装，光驱动就得折腾半天，这在测试开发领域太常见了。
Playwright 最核心的工程思路，是把这些历史遗留问题整体打包解决掉。它不依赖外部单独下载的驱动文件，而是通过内置的浏览器驱动和一套统一的协议接口和浏览器内核直接通信，第一次安装就能自动下载匹配版本的浏览器，省掉了“驱动版本对不上”这个磨人的环节。
从架构上看，它把常见的“浏览器实例—标签页—页面元素”抽象成了三层模型：Browser、BrowserContext 和 Page。这套分层不只是概念区分，几乎决定了你后续所有代码怎么写。三者关系类似“虚拟机—隔离环境—会话窗口”。操作页面内元素基本都在 Page 层，为了模拟不同用户或者隔离脏数据就在 Context 层切换，只要底层 Browser 保持一个实例就能复用。
1.2 一套 API 驱动三种浏览器内核
Playwright 支持的浏览器包括 Chromium 系、Firefox 和 WebKit 系，API 完全一致，并没有为某种浏览器单独搞特殊接口。这背后是它对每种内核做了一层封装，把各家浏览器暴露出的差异收敛到同一个操作模型里。实际效果就是：你裸奔式地在本地把逻辑写好后，在 CI 上完全可以并行跑三种浏览器的兼容性检查。
不过说实话，日常开发中绝大多数项目只需要 Chromium 一种内核就够了。特别是你做的不是严格兼容性验证，而是或者网页爬虫，用多个内核反而会拖慢执行速度，还占内存。刚开始学的话，我建议优先把 Chromium 这条路跑通，Firefox 和 WebKit 随用随加就行。
另外要提的是，它默认就有无头模式和普通有头模式的切换。无头模式跑起来快，适合批量执行；有头模式适合调试阶段观察界面交互。launch() 方法默认 headless 是 True，如果你在学习阶段希望看到浏览器窗口，需要显式传 headless=False。不要默认它是带界面的，我第一次调试时找不到窗口，查了半天才发现这个默认值。
1.3 自动等待机制到底是怎么来的
老一代自动化脚本最大的不稳定来源是“人肉等待”。用 time.sleep(3) 硬等三秒，页面快的时候浪费时间，慢的时候照样崩溃。Playwright 在这一点上做了比较彻底的重构：所有核心操作如 click、fill 等，内置了一套“操作可达性检查”机制，会自动等元素可见、可交互、不再被遮拦，等不到就在超时阈值内继续等。
这个设计初看只是“更智能的等待”，实际影响很大。它把脚本的写法从“动作 + 显式等待”变成了“动作本身带条件”。不需要每个点击前都加一句“等元素出现”，代码会简洁很多。
但要注意，它的自动等待不等于“替你做正确判断”。比如页面里同时存在多个匹配元素时，严格模式下很多操作会直接报错，而不是帮你瞎猜一个。这个保护机制是为了避免误操作到错误元素，我自己刚开始没搞懂这个设计反而觉得它很啰嗦，后来排查定位问题才发现这个强制约束特别有价值。
2. 环境搭建与第一个可运行脚本
2.1 安装步骤与浏览器内核下载
做 Python 环境最省心的方式是使用虚拟环境，避免污染系统级 Python。建议先建一个干净的 venv，然后直接安装库：
pip install playwright安装完只是装好了库本体，还需要下载浏览器内核：
playwright install chromium这一步需要网络下载，文件体积不小。如果是公司内网或者断网环境，会稍微麻烦一点，但一般开发机直接执行就行。装完之后可以用一条很短的脚本启动浏览器验证环境是否正常：
from playwright.sync_api import sync_playwright with sync_playwright() as p: browser = p.chromium.launch(headless=True) page = browser.new_page() page.goto("https://example.com") print(page.title()) browser.close()代码跑通后，你会看到 example.com 的页面标题打印出来，说明库、驱动、浏览器内核这条链路已经全通了。
2.2 同步 API 与异步 API 怎么选
Playwright 在 Python 里给了两套接口，对应 sync_playwright 和 async_playwright。前者是同步阻塞式写法，后者要配合 asyncio。
对刚入门的同学，我比较推荐先学同步接口。理由很朴素：大部分日常脚本是“串行操作一个浏览器”，同步写法思维负担最小，和代码实际执行顺序完全对应，出错了也容易定位。我自己写爬虫和回归脚本时绝大多数场景都用同步版，只有需要高并发跑多个浏览器任务时才考虑异步。
切换两套写法不只是换一个导入入口，代码风格差异还是挺大的。比如同步版的新页面可以用 with context.expect_page() 这种上下文管理器，异步版则要用 await 等待事件。初学阶段没必要同时搞两套，先把同步版练熟，理解核心对象模型，再迁移异步版会顺畅很多。
2.3 最小脚本的逐行拆解
上面的三行核心代码，我拆开讲一下每步做了什么。
第一步创建一个浏览器实例。这个实例可以理解为无头模式下的“一个完整浏览器进程”，后续所有标签页都归属它管理。一个脚本里建议只启动一次，不要每次操作都 new 一个浏览器，那是很大的性能浪费。
第二步调用 new_page() 创建页面对象。这里的页面相当于浏览器里的一个标签页，也是你查 DOM、点按钮、填表单的主战场。默认新标签页是空白页，需要用 goto 导航到目标网址。
第三步执行 goto 跳转。这个方法默认会等待页面触发 load 事件。但要留意，load 触发并不代表页面上所有异步内容都渲染完毕，所以后续定位操作仍然依赖自动等待机制，不能因为 goto 返回了就认为万事大吉。
2.4 建议的目录结构
学习阶段脚本可以随便写，但一旦项目跑起来，建议按“公共方法、页面对象、用例”分层组织：
automation/ ├── main.py ├── common/ │ └── browser.py ├── pages/ │ ├── login_page.py │ └── home_page.py └── cases/ └── test_login.py目录规范是一种投资。刚开始写单文件脚本很快，过两周回来看，发现连哪个函数是干嘛的都忘了。如果你能承受代码维护成本，建议尽早从单文件切换到分层结构。
3. 基础操作实战：定位元素与页面交互
3.1 选择器的优先级问题
页面交互的第一步永远是“找到要操作的元素”。Playwright 支持了多种定位方式：CSS 选择器、文本选择器、角色选择器、XPath、以及基于现有元素再链式缩小范围的 locator。
使用优先级上，我的经验是：用户可见文本 > 语义化角色 > 稳定的 CSS 属性 > XPath。优先用接近“人眼识别”的定位方式，而不是死磕一长串 CSS 层级路径。原因很简单：前端页面稍作改版，CSS 类名和 DOM 结构最容易变，但页面上的按钮文字“提交”“取消”相对稳定。
举例来说，一个登录按钮写成：
page.get_by_role("button", name="登录").click()要比写成下面这种 CSS 路径稳定得多：
page.locator("div.form-footer > button.btn-primary.submit").click()当然 CSS 也有价值，比如定位表格里特定结构的单元格时，XPath 和 CSS 依然是好帮手。但凡是能用文本或角色表达清楚的，我不推荐动用复杂层级表达式。
3.2 常用的定位器写法
以下是我平时最常用的几种，对新手来说这坨语法可以先直接抄：
page.get_by_text("联系客服") # 文本定位，找包含该文本的元素 page.get_by_label("用户名").fill("admin") # 表单标签定位，适合表单字段 page.get_by_placeholder("请输入邮箱").fill("demo@example.com") # 占位符定位 page.locator("#main .card").first() # CSS 定位，first 取首个匹配 page.locator("xpath=//button[@type='submit']") # 显式 XPath 写法 page.frame_locator("#iframeId").get_by_text("详情") # 处理 iframe 内元素文本定位有一个地方容易踩坑：get_by_text 默认是“包含匹配”，不是“精确匹配”。页面上如果同时有“登录”和“登录后查看”，用 get_by_text("登录") 会匹配两个元素，严格模式下直接报错。遇到这种情况，可以加 exact=True 参数改成精确匹配。
表单元素的现象很有意思：label 和 placeholder 在 HTML 里是两个不同的属性，但 Playwright 的 get_by_label 会自动关联 label 标签的 for 属性和控件 id，这在填写表单时确实很省事，不用先定位到输入框再逐层找 label 关系。
3.3 点击、输入、取值三种高频操作
点击操作：
page.get_by_role("button", name="提交").click()click 触发前会自动等待元素可点击，常见被遮拦场景也能自动滚到可见区域。但遇到“点击后新页面打开”或“点击后弹窗出现”，需要在点击前就注册等待事件：
with page.expect_popup() as popup_info: page.get_by_text("新窗口打开").click() popup = popup_info.value这样才不会漏掉新开的标签页，否则新窗口定位会变得很被动。
输入操作推荐用 fill，而不是 click 后逐字符 send_keys。fill 更接近“赋值”，会把输入框原有内容直接覆盖，效率高，也没那么多焦点问题。个别富文本编辑器可能不支持 fill，需要模拟输入时再考虑 type。
取值操作里最常用的是 text_content() 和 inner_text()。两者差别在于保留空白字符的方式不同，inner_text 更接近“肉眼看到的文本”。
还有个会被忽视的快捷键操作：按 Enter 提交表单可以直接用：
page.get_by_text("搜索").press("Enter")在一些没有显式提交按钮的单页应用里，这个动作比找按钮再点击要稳得多。
3.4 严格模式的坑
我前面提到严格模式。简单说，Playwright 在定位元素时默认要求“选出来的结果必须唯一”。比如你写 get_by_text("确认")，但页面上有两个“确认”按钮，它直接报错，而不是默默选第一个。
有人会嫌麻烦，想用 .first 或者索引来“降级处理”。我的建议是：能用唯一语义定位，就尽量不要依赖 first。页面出现多个同样文案的确认按钮，本身意味着产品逻辑或测试数据可能有问题，脚本早早暴露这个问题反而是好事。真想降级时，再用 .filter 或 :nth-match 收紧范围。
4. 稳定性关键：等待策略与加载状态
4.1 自动等待的可操作性检查点
Playwright 包装点击动作时，会去检查如下几点：元素是可见的、元素在布局中是稳定的、元素能接收事件、元素不是 disabled 或 readonly（可编辑性）、元素没有遮挡物。
这些检查点集合在一起，配合默认 30 秒超时，能覆盖绝大多数“页面元素还没就绪就操作”的问题。实操中我最常用到的是“遮挡检查”场景，比如按钮被一个加载中的遮罩层挡住，老脚本往往会因为遮罩还在就点击失败，而 Playwright 会等遮罩消失再操作。
这个自动等待设计很巧妙，但也不要滥用。它不等于“所有场景都能智能判断”。比如页面里有接口轮询导致按钮状态来回切换，自动等待检查通过后状态又变了，这种场景仍然需要业务层面的重试逻辑。
4.2 显式等待的适用时机
自动等待覆盖了大部分场景，但有一类情况还是需要手动等待：等待一个接口的响应、等待某个特定元素出现或者消失。
页面里最常用的是 wait_for_selector 和 wait_for_load_state：
page.wait_for_selector(".result-item", timeout=10000) page.wait_for_load_state("networkidle")wait_for_selector 会把“元素出现”作为条件，配合 timeout 参数控制最多等多少毫秒。在实际爬取中我经常用“元素消失”判断一个加载过程结束：
page.wait_for_selector(".loading-mask", state="hidden")加载遮罩消失再继续后续动作，这也是减少不稳定脚本的一种手段。
注意 networkidle 这个状态。它代表没有任何网络连接保持 500 毫秒以内，是好用的“页面安静”信号。但如果页面有持续轮询的接口，networkidle 可能永远等不到，所以不要盲用。
4.3 不要过度依赖睡眠等待
用 time.sleep 解决等待是我最不推荐的写法。它本质上是一种赌博，赌一个固定时间足够，一旦网络波动就会产生连锁失败。比较好的处理思路是：
先用默认自动等待机制，如果确实不稳定，再在关键节点用显式等待条件；最后才考虑用 sleep，且要短时间使用并注明原因。
我在实际项目中遇到过一个特殊页面，某个动画效果会持续 800 毫秒，可点击状态在动画结束后才生效。自动等待判断时可点击状态似乎已通过，但实际点击时动画还在遮挡。这种情况我用 wait_for_timeout(1000) 反而最简单，只要注释写清楚为什么等，这个临时方案完全可接受。
4.4 超时的默认值与修改方式
Playwright 的默认超时时间是 30 秒，这个可以在很多层面调整。最细粒度的是在单个操作上：
page.get_by_text("登录").click(timeout=15000)也可以全局配置：
page.set_default_timeout(15000)但超时时间不是越长越好。过长的超时会让失败用例拖到接近分钟的级别，排查问题时相当难受。建议根据业务接口平均响应时间设定合理的超时，比如公共操作 15 秒，个别慢接口再单独放宽。
5. 常见问题排查与调试技巧
5.1 定位超时的三种典型原因
出现 timeout 之后，我一般按这个顺序排查。
第一，选择器没有匹配到任何元素。打开浏览器调试模式看看页面实际结构，确认元素确实存在，检查是否在 iframe 里、是否是动态渲染的组件、是否用了 shadow DOM。
影子节点要特别注意，普通 CSS 选择器进不到 Shadow DOM 内部，需要用 pierce 相关选择器，或改用用户可见文本定位。
第二，元素存在但不可交互。常见原因是被遮挡、被隐藏、不是 enabled 状态。可以临时在页面里查看元素坐标和可见性，判断是哪种情况。
第三，新页面没有切换上下文。点击后打开新标签页，后续定位还停留在旧 page 上，自然找不到元素。这块我在第 3 节讲了用 expect_page 提前捕获新页面。
5.2 严格模式报错的处理办法
报错信息通常会提示“resolved to N elements”，说明定位器命中多个元素。
先别急着用 first，而是想清楚这些元素是不是应该同时存在。比如页面导航栏和正文里都有“设置”两个字，那可以通过角色加文案组合限定或利用父级结构缩小范围。更精细的写法：
page.locator(".settings-panel").get_by_text("设置")这比单纯用 .nth(0) 靠谱，因为它把定位范围收缩到了目标区块内。
5.3 调试时打开有头模式
脚本不稳定时，第一件事就是把 headless=False 打开，加一个合理的慢速动作参数，让浏览器放慢执行：
browser = p.chromium.launch(headless=False, slow_mo=500)slow_mo=500 表示每个操作之间延迟 500 毫秒，这样你可以肉眼看清楚每一步点击发生在哪里，定位错没错一眼就能发现。调试完再切回无头模式跑批量。
5.4 录制工具与代码生成
如果你完全不想手写选择器，Playwright 自带 codegen 工具，可以录制浏览器操作并生成对应代码。启动命令行：
playwright codegen https://example.com它会打开一个浏览器窗口，你手动点击、填写、跳转，旁边同步生成同步版 Python 代码。生成的分层不是最优，但作为选择器的“抄作业”参考完全够用。
trace 也是调试利器。录制脚本执行过程中的页面快照、网络请求和浏览器控制台信息，之后再回放分析，对定位偶发失效问题很有帮助。
5.5 浏览器启动失败的几种情况
playwright install 装完浏览器后，启动依然失败，通常和系统缺少依赖库有关。常见提示包括缺少某些系统库字符集或动态链接库。
排查很简单：新装一个干净环境，重新执行 playwright install chromium，通常能自动装好缺失依赖。个别 Linux 容器环境里还需要手动安装系统依赖，可以按具体库名搜索安装。这段出的问题基本都是环境层面的，不是代码逻辑，不用太焦虑。
6. 收个尾：我这两天的一点体会
学 Playwright 的前一两天，最容易犯的错误是抱着“练手心态”随便写脚本，元素定位用最粗暴的 first，等待全靠 sleep，跑了几天之后脚本开始变得脆弱不堪。真正让它稳定下来，靠的是理解自动等待机制、梳理好定位策略、以及项目开始时就把目录结构和公共方法规划清楚。
如果你刚准备上手这套工具，我建议今天先把环境、三个分层对象和定位器两种写法吃透。明天再继续看表单填写、请求监听和 Cookie 处理，逐步把能力树补完整。这套框架的路径依赖比较强，前面基础打牢了，后面学什么都很快。
