做Web自动化这些年，我换过好几套技术方案，如今自己维护的日常工具链里，Playwright几乎成了必选项。它不是一个只解决“点击一下按钮”的小脚本，而是围绕浏览器自动化沉淀出来的完整技能库：从底层页面驱动、等待策略、网络拦截，到登录态管理、文件下载、定时巡检，都能用同一套API串起来。这篇就把基于Playwright的浏览器自动化技能库从原理到实战完整拆开讲一遍，既适合刚接触自动化的新人，也适合已经在用Selenium或其他工具、想迁移过来的人。
先说我为什么会围绕Playwright做技能库。早期我一直用单一脚本解决单一需求，脚本之间互相重复，今天发版明天改版，选择器一动就全线崩溃。真正把自动化当工程做，是从“技能库”这三个字开始的：不是堆一堆脚本，而是把浏览器能力抽象成可复用的模块，让团队里任何人拿到后都能快速写业务场景。Playwright在这件事上帮了大忙，它把浏览器控制、自动等待、上下文隔离、网络请求接管这些底层逻辑都封装得比较干净，我只需要关心业务怎么表达。
1. 为什么是Playwright：项目定位与核心价值
1.1 浏览器自动化到底在控制什么
很多人一上来就写page.click()，但对底层发生了什么完全没有概念。浏览器自动化的本质，是外部程序通过某个通信通道，向浏览器进程发出指令，让浏览器去执行导航、点击、输入、截屏等操作，再把运行结果返回给外部程序。
Playwright走的路线是直接和浏览器内核层面的调试协议通信。以Chromium系浏览器为例，它底层对接的是调试协议（通常称为CDP），通过WebSocket传输命令和事件。这意味着Playwright不是在浏览器外面“遥控”，而是钻进了浏览器内部，获得的事件类型和数据结构比传统方案更丰富。比如网络请求的细节、控制台日志、性能指标、DOM变化，都能以事件流的方式拿到。
传统WebDriver方案则是通过一套HTTP接口驱动浏览器的驱动进程，驱动进程再转译成浏览器原生支持的操作。这两套架构的区别，直接体现在日常体验上：CDP方案能听到浏览器里发生的一切，事件粒度更细；而WebDriver方案更像是站在门口喊话，很多内部事件要靠额外手段才能捕获。
理解这一层很重要，因为它决定了技能库里哪些能力能做、怎么做。比如我要监听某个接口返回的状态码，在Playwright里只需要注册一个response事件就能拿到响应对象，不需要去数据库里翻日志。这种“跟浏览器站在一起”的视角，是所有高级玩法的基础。
1.2 我对比过几套工具后，为什么最终选Playwright
先说结论：不是Selenium不好用，而是Playwright在某些高频痛点上确实更省事。我从四个维度做了一张对比表，这些维度也是我判断一套自动化工具是否适合做技能库底座的标准。
| 对比项 | Playwright | Selenium WebDriver | Puppeteer |
|---|---|---|---|
| 等待机制 | 内置自动等待，操作前自动检查可见、可点 | 早期以显式等待为主，需要手动写ExpectedConditions | 需要手动实现等待逻辑 |
| 多标签页/多账号 | BrowserContext原生隔离，一个标签页一个上下文 | 通过WindowHandle切换，心智负担较重 | 依赖多个Browser，较重 |
| 网络层控制 | 支持路由拦截、请求修改、响应mock | 能力较弱，依赖第三方工具 | 支持较好，但浏览器范围窄 |
| 浏览器支持 | Chromium系、Firefox、WebKit一套API通吃 | 支持广，但各浏览器驱动表现有差异 | 基本只支持Chromium系 |
| 调试体验 | 自带UI模式、trace回放、inspector，排查非常直观 | 依赖IDE插件和外部工具 | 有基础调试，但功能较少 |
这套对比不是我凭空想的，而是自己接过真实项目之后一点点试出来的。多账号隔离这个需求，以前用Selenium写一套“多窗口管理”要处理各种WindowHandle边界情况，浏览器一弹窗就得重新校队句柄，特别容易出问题。Playwright的BrowserContext把每个上下文当成一个独立小浏览器，账号A和账号B天然隔离，代码几乎零额外成本。
另外让我下决心迁移的还有一个细节：Playwright的自动等待不是简单的“等元素出现”，而是会等元素达到可操作状态，比如等待元素稳定、没有被遮挡、接收事件能力正常。这些细节让脚本误报率低了很多。原来我维护的脚本，大量时间都在跟“什么时候页面加载完”作斗争，迁移到Playwright之后，这类问题减少了九成以上。
2. 技能库的整体设计：模块划分与代码组织
2.1 从“脚本”到“能力库”的第一步
一套合格的技能库，至少分两层：底层是“浏览器能力封装”，上层是“业务场景编排”。很多新手容易犯的错，是把业务逻辑和浏览器API混在一起写，比如在测试用例里直接调page.goto()、page.fill()，今天换一个场景，又要复制一遍。
我建议先做一层“会话管理”。每个自动化任务都需要启动浏览器、打开页面、清理资源，这一步如果每个脚本都写一遍，团队里很快就百花齐放了。封装后的会话管理模块大概长这样：
from playwright.sync_api import sync_playwright class BrowserSession: def __init__(self, headless=True, viewport=None): self._playwright = sync_playwright().start() self._browser = self._playwright.chromium.launch( headless=headless, args=["--disable-blink-features=AutomationControlled"] ) self._context = self._browser.new_context( viewport=viewport or {"width": 1280, "height": 720}, locale="zh-CN", ) self._page = self._context.new_page() @property def page(self): return self._page def close(self): self._browser.close() self._playwright.stop()这段代码里有一个我自己的习惯：--disable-blink-features=AutomationControlled这个参数，能让某些依赖浏览器指纹判断的页面少一些脾气，但这个不是“隐身术”，它只是消除一个最常见的自动化痕迹。真正的可靠性来自你的脚本本身：等待策略对不对、选择器有没有歧义、页面状态判断是否完整。
有了这个会话类，所有业务脚本都这样写：
session = BrowserSession(headless=True) page = session.page page.goto("https://example.com") # 你的业务操作 session.close()这种做法的好处是，团队里有人想换浏览器引擎，只需要改BrowserSession一个文件，几十个业务脚本完全不受影响。
2.2 业务层与基础层的边界在哪里
技能库最容易失控的地方，就是模块拆得太细，最后变成“代码到处都是，没有一处好改”。我自己的分寸感是：基础层只放“跟具体页面无关的能力”，业务层才放“跟具体页面相关的步骤”。
基础层放什么？页面通用操作、文件下载、请求监听、文本断言、截图、控制台日志收集。这些模块不关心你测的是登录页还是下单页。业务层放什么？登录、搜索、下单、审批，这些才是和具体业务绑定的流程。基础层就像工具箱，业务层就像装配线。
举个例子，我在基础层写过一个assert_text的封装：
def assert_text(page, selector, expected, timeout=5000): locator = page.locator(selector) locator.wait_for(timeout=timeout) actual = locator.inner_text().strip() assert actual == expected, f"期望文本是 {expected}，实际文本是 {actual}"这个函数没有绑定任何业务页面，但它把“等待元素出现、获取文本、校验结果、错误信息格式化”这几件事一次性做完。上线前我把这个函数沉淀进了技能库，之后所有业务脚本都复用它，遇到“快速点击导致结果还没渲染，断言提前执行”的问题，因为内置了wait_for，一次性解决。
业务层的封装则是这样的：
class LoginPage: def __init__(self, page): self.page = page def login(self, username, password): self.page.goto("/login") self.page.fill("#username", username) self.page.fill("#password", password) self.page.click("button[type=submit]") self.page.wait_for_selector(".user-info")业务脚本只需要知道LoginPage有个login方法，不需要知道登录页有哪些选择器、登录后等哪个元素出现。这就是边界。
2.3 多环境配置不要写死在代码里
技能库如果要在开发、测试、生产环境之间反复切换，最忌讳的就是把地址、账号、超时时间硬编码在脚本里。我一般在项目根目录放一个config.py，用环境变量或本地配置文件方式管理：
import os BASE_URL = os.getenv("APP_BASE_URL", "http://localhost:8080") USERNAME = os.getenv("APP_USERNAME", "") PASSWORD = os.getenv("APP_PASSWORD", "") HEADLESS = os.getenv("HEADLESS", "true").lower() == "true"账号密码不要提交进仓库，本地.env文件加上.gitignore忽略。这点我吃过亏，曾经有一次脚本库传到了公共仓库，里面带了一个测试账号的明文密码，事后改密码、排查泄露范围，折腾了小半天。后来我养成了一个习惯，技能库里凡是涉及密钥、token的一律走环境变量，代码里只留os.getenv()。
配置做完后，CI环境和本地环境都能用一套代码。本地想看看浏览器真实执行过程就设置HEADLESS=false，CI里要求无头运行就HEADLESS=true，切换成本几乎为零。
3. 动手实现：核心技能模块逐个击破
3.1 页面交互与智能等待机制，为什么我很少用sleep
在Playwright之前，很多人写自动化会写一堆time.sleep(3)，等3秒页面加载。这种做法极其脆弱，快的时候浪费3秒，慢的时候3秒不够。Playwright的内置自动等待是我最喜欢的功能之一，大部分情况下你不需要手动等待，它会在执行操作前自动检查元素是否可见、是否可点击、是否处于接收事件的状态。
比如这个登录场景：
def login(page, url, username, password): page.goto(url) page.fill("#username", username) page.fill("#password", password) page.click("#login-btn") page.wait_for_selector("#dashboard .welcome")这段代码表面上看起来平平无奇，但是每一步背后都有检查。fill会先等输入框可交互，click会先等按钮可见且没有被其他元素遮挡。哪怕前端在点击之后要发请求、等响应、重新渲染，wait_for_selector也能保证最终结果出现后才往下走。
我实际写技能库时会给团队一条铁律：能用自动等待解决的事，绝不用sleep()。如果某个页面确实有特殊的动画过渡，我更倾向于等待特定元素而不是固定秒数。固定秒数意味着无论上线还是回归，脚本都在盲等，出了环境波动就会变成一堆“偶发失败”。
关于选择器，还有两个细节值得一提。第一，优先使用page.get_by_role()、get_by_label()这类语义化选择器，别死磕CSS路径，页面结构调整时语义选择器往往还活着。第二，用locator.first、locator.last或locator.nth(index)处理一组元素时，要注意元素数量变化，先断言数量再操作，脚本会可靠很多。
3.2 请求与响应捕获：让UI自动化也能“看”网络数据
Playwright支持在页面级别监听网络事件，这个能力让技能库能做很多传统UI自动化做不了的事。最常见的需求是：点击按钮之后，页面发了一个POST请求，我想知道这个请求返回了什么，并把它和界面上的结果做一致性校验。
代码实现很简单：
def capture_response(page, url_pattern): captured = {} def handler(response): if url_pattern in response.url: captured["status"] = response.status captured["body"] = response.text() page.on("response", handler) return captured假设页面上有个图表组件，点击刷新按钮后，前端会请求/api/chart-data。我在技能库里这样用：
page.click("#refresh-btn") wait = page.expect_response("**/api/chart-data") # 点击之后等待请求完成 with wait: page.click("#refresh-btn") response = wait.value data = response.json()这里的expect_response不是“轮询查一下”，而是从点击前就开始监听，点击动作一触发，只要请求满足条件，就会等待它完成。比起被动监听，这种主动匹配的方式更精准。我后来做数据核对，全部依赖这个模式：UI上显示的数值必须和接口返回的数值一致，截图对比反而容易漏掉动态内容。
技能库里有了网络捕获，还衍生出了另一个实用功能：页面加载完成的判断。有些页面一个按钮点了之后，界面半天没反应，但其实请求已经发出去了，只是网络慢。我一般同时监听request的结束事件和某个特定元素出现，两者都满足才继续执行，解决了不少“明明数据加载了但脚本还是报错”的案例。
3.3 登录态保持与多账号隔离：不要每次从头登录
自动化任务一大半时间都花在登录上。如果要做数据采集或者定期巡检，每次跑脚本都走一遍登录流程，不仅慢，还容易因为验证码、二次验证卡住。技能库必须解决“登录一次，多处复用”的问题。
Playwright的storage_state做这件事非常顺手。第一次登录成功之后，把当前上下文的存储状态保存到本地文件：
# 登录成功后 state = context.storage_state(path="state.json")后续脚本启动时直接加载：
context = browser.new_context(storage_state="state.json") page = context.new_page()这里存的不仅仅是Cookie，还包括localStorage、sessionStorage等浏览器内部状态。访问受登录保护的页面时，直接就带上了登录身份。
多账号隔离也是靠上下文实现。每一种业务身份开启一个独立context，它们之间Cookie完全隔离，互不干扰。我做过一个数据上报的巡检脚本，需要同时使用管理员账号和普通用户账号，分别核对不同权限下的功能表现，用两个上下文并行跑，效率和隔离性都很好。
有一点要提醒：storage_state不是永不过期。有的登录态有效期只有一两个小时，有的服务端还会强制踢人。我一般会在脚本开头做一个“登录状态探活”，访问一个只有登录后可见的页面，如果跳到登录页，就自动执行重新登录流程，再刷新state.json。这样技能库里的登录态文件始终是“活着”的。
3.4 文件下载与导出：不能只检查“下载成功”
很多系统都有导出Excel、PDF、CSV的功能，UI自动化要验证“点了导出有没有真把文件下载下来”。Playwright把下载流程封装成了事件，我习惯写成这样一个模块：
def download_file(page, trigger_selector, save_path): with page.expect_download() as download_info: page.click(trigger_selector) download = download_info.value download.save_as(save_path) return save_path执行完之后，我还有一种追加校验：读一下文件大小，低于某个阈值就认为导出异常。经验是，很多导出功能在数据量少时返回空模板文件，脚本如果只判断“下载动作是否触发”，根本发现不了内容缺失。
处理CSV或Excel时，我在技能库里放了两个解析器：CSV直接用Python标准库解析行数和首行表头；Excel则需要第三方库支持，逻辑类似。解析完之后用断言对比行数是否和服务端返回的记录数一致。这一套流程下来，导出功能的质量我心里基本有底。
3.5 定时执行与结果汇总：把技能库变成“无人值守”
技能库搭好之后，自然要让它定时跑。最简单的做法是交给操作系统的定时任务：Windows下用任务计划程序，Linux或macOS下用cron。我这里贴一个cron示例，每天早晨9点跑一次巡检脚本：
0 9 * * * cd /path/to/skill-library && /usr/bin/python3 job.py >> logs/job.log 2>&1但定时任务只解决“跑起来”，不解决“跑完怎么知道结果”。我习惯在技能库里加一个结果汇总模块：每次跑完，把成功用例数、失败用例数、截图路径、错误信息统一收集，再通过消息机器人推送到工作群。这样早上到工位打开手机就能看到巡检结果，不用每天手动查日志。
还有一个经验：长期无人值守的任务，日志必须拆分。按日期切分，单个文件不要无限追加，否则半年后日志文件动辄几个GB，排查问题都无从下手。我在技能库里统一用logging模块输出结构化日志，内容包括任务名、执行时间、操作步骤、结果状态，配合按天滚动，排障速度会快很多。
4. 真实场景中的落地案例：从“能跑”到“能用”
4.1 后台表单回归：以前半小时，现在三分钟
我最早把技能库实践到极限的，是一个后台管理系统的表单流程回归。那个系统一个完整流程涉及十来张表单页，每页都要填基础信息、扩展信息，再提交、审核，全部手工点一遍要半小时。技能库落地后，我写了一个场景脚本：
def test_create_order_flow(page, test_data): create_page = OrderCreatePage(page) create_page.goto() create_page.fill_basic_info(test_data.basic) create_page.fill_extend_info(test_data.extend) create_page.submit() result_page = OrderResultPage(page) result_page.wait_until_loaded() order_no = result_page.get_order_no() assert order_no is not None, "提交后没有生成订单号" # 后续回到列表页校验 list_page = OrderListPage(page) list_page.goto() assert list_page.search_order_no(order_no)这套脚本跑完一遍只需要三分钟，而且每一步的执行细节都被封装到了页面类里。后续页面改了字段，我只需要改对应的页面类，流程脚本一行不动。可以说，这套模式真正让自动化从“演示Demo”变成了“回归工具”。
4.2 内容变更加载监测：盯着公告页面的“新消息”
另一个让我印象深刻的落地场景，是监控某个内部公告页面。那个页面内容更新不固定，但业务方又很依赖最新消息，人工刷新太费劲。我写了一个监控脚本，每半小时跑一次：
def monitor_content_change(page, known_hash, url): page.goto(url) content = page.locator(".announcement-body").inner_text() current_hash = hash(content) if current_hash != known_hash: notify("公告页内容更新了") return True, current_hash return False, known_hash这个脚本不是为了测试系统，而是为了持续采集内容变化，本质上是“浏览器当传感器”的用法。它跑了一个月，确实捕获到了几次内容更新，业务方评价说“比眼睛盯屏靠谱”。技能库的应用范围，可以完全不限于测试，这个案例让我对“浏览器自动化技能库”这个概念的理解又深了一层。
4.3 把性能数据也一并抓回来
除了功能验证，技能库里我还留了一个性能采集模块。利用page.evaluate()直接读取浏览器性能数据，配合页面卸载和重定向，可以拿到DNS查询时间、TCP连接时间、首字节时间这些指标：
def collect_perf_metrics(page): return page.evaluate("""() => { const nav = performance.getEntriesByType('navigation')[0]; return { dns: nav.domainLookupEnd - nav.domainLookupStart, tcp: nav.connectEnd - nav.connectStart, ttfb: nav.responseStart - nav.requestStart, domContentLoaded: nav.domContentLoadedEventEnd - nav.navigationStart }; }""")这个模块做不了专业压测，但对“页面到底卡在哪一步”这种问题很管用。技能库的价值就在于，同一个浏览器会话里，功能验证和性能数据可以一箭双雕，不必为了一个指标单独搭一套环境。
5. 常见问题与排查：这五个坑我基本都踩过
5.1 选择器定位失败：别急着改代码，先想为什么
定位失败是自动化脚本的头号杀手。常见的几种原因：元素在iframe里，元素在Shadow DOM里，元素存在但不可见，页面用了动态id导致每次刷新都不同。
iframe的处理我单独写了模块。Playwright里切入iframe很直接：
frame = page.frame_locator("#main-iframe") frame.locator("#submit-btn").click()Shadow DOM则用穿透选择器或直接定位到shadow host再进去。最怕的是动态id，这个没有银弹，只能让前端配合，在关键元素上加稳定的>
