从去年第一次把 Playwright 正式写进自动化项目到现在刚好一个完整周期。第一版笔记主要解决的是“怎么跑起来”安装、选择器、点击、截图脚本能录能回放在当时已经觉得很有成就感。但当这套基于 Playwright 的 UI 自动化真的跑到三个月之后我才发现“跑起来”和“稳定好用”完全是两回事。跑起来不代表稳定稳定不代表可维护可维护也不代表能随时应对前端框架的迭代。所以这个第二版我不想再把 API 列表复述一遍而是打算把这一年在动态页面、iframe、定位器策略、AI 辅助生成脚本、MCP 联动这些真实场景里趟出来的经验重新梳理一遍。如果你也在做 UI 自动化或者正准备把手工测试用例转成可持续回归的自动化资产这篇内容应该能帮你少踩几个坑。1. 第二版到底更新了什么从可用到好用的转变1.1 第一版的核心其实是“让工具先跑起来”首版文章的逻辑非常朴素先装 Playwright再用录制工具快速生成一段脚本然后把它封装成一个用例。这套流程对新手很友好但实际放到项目里问题马上暴露出来。录制生成的脚本最大的问题是定位器太“死”。很多录制工具倾向生成基于路径的严格选择器围绕某个元素的 DOM 位置。页面结构只要一变脚本就断。而且录制脚本里没有业务意图你给后来的人看他看不懂为什么顺序是“先点这里再填那里”。维护的人一旦离职或者转岗这套自动化就慢慢变成无人维护的“僵尸资产”。所以第二版的前提是默认读者已经知道怎么安装和启动浏览器我们应该把精力放在更值钱的问题上——动态内容怎么稳定处理、用例怎么组织结构化、回归跑挂了怎么快速定位、以及现在很火的 AI 能不能真的帮上忙。1.2 真正让 UI 自动化变质的三个变量我这一年做下来的感受是一套自动化能不能长期跑技术能力改变只占一小部分更大的影响来自三个变量。第一个变量是页面本身的动态化程度。现在的前端已经不是十年前那种“点一次链接刷新整个页面”的形态而是大量使用 React、Vue 这类框架DOM 会被反复重建元素可能同时存在多个副本有些内容还在 iframe 里。这对自动化脚本的等待逻辑和定位策略提出了很高的要求。第二个变量是团队规范的一致性。有的团队有统一的测试账号体系有测试环境专用的测试数据执行结果一目了然有的团队共用一套开发环境数据天天变某条用例早上能过下午就挂最后变成靠运气。后面我会专门说怎么用结构化用例 数据隔离来缓解这个问题。第三个变量是工具生态的演进。Playwright 这一年迭代很快官方支持了 trace viewer、代码生成、断言库还有 MCP 服务这也直接推动我重新写一篇第二版。因为第一版里很多需要自己费劲实现的“等待策略”“失败现场采集”现在已经是开箱即用方案自然得跟着改。1.3 给新读者和老读者的阅读建议如果你是刚接触 Playwright建议你先照着 Quickstart 文档启动一个浏览器再回来看这篇文章。我这里不会再讲最基础的“如何启动一个空白页”而是重点讲你会更早遇到的那些“怎么定位都不稳定”“iframe 里找不到元素”的问题。如果你已经在用 Playwright 做项目建议重点看第三、四、五章。这几章分别对应定位器选择策略、用例组织结构、以及如何用 MCP/AI Agent 提升效率是目前生态里变化最快、也是讨论最多的部分。每个人的环境不同踩坑方式可能不完全一样但排查思路是可以迁移的。2. 环境准备离线安装、浏览器版本和团队协作的坑2.1 安装包与二进制浏览器要分开看待很多新手第一次跑 Playwright 会卡在安装阶段一个常见误解是“装完 pip 包就能用”。实际上Playwright 分两层一层是 Python 或 Node 端的 API 包另一层是它独立管理的浏览器二进制文件。这两层是分开安装的。pip install playwright1.44.0 python -m playwright install chromium第二行才是真正去下载 Chromium 浏览器。它会放到本地缓存目录与操作系统里已安装的 Chrome 互不干扰。这个设计的好处是版本可控坏处是如果你所在的网络环境不适合直接下载或者公司内部网络限制比较多就必须走离线方式。我同事的实践路径是找一台能拿到完整安装包的机器先把浏览器二进制下载好然后通过内部文件服务器分发。所有执行任务的机器上把浏览器缓存目录指向同一个公共路径PLAYWRIGHT_BROWSERS_PATH/data/browsers python -m playwright install chromium --with-deps如果机器缺少系统级依赖库加上--with-deps会比较省事但这个参数通常需要 root 权限在 CI 环境里要提前确认好。离线机器上如果不想现装系统依赖也可以提前在基础镜像里把依赖库打进去那样运行时只解压二进制文件就行。2.2 把浏览器版本写进依赖与团队成员对齐Playwright 的 API 包和浏览器二进制是有版本对应关系的。比如 1.44.0 这个版本对应某个特定 Revision 的 Chromium两个要件不匹配运行时会直接报错“Executable doesnt exist”。所以团队协作时我最推荐的做法是把 Playwright 的版本号写死在依赖文件里并在 README 里标记对应的 Chromium 版本。不要写playwright1.40这种宽松约束因为上游一旦发布新版本各人本地拉的版本不一致脚本行为就会分叉。playwright1.44.0 pytest-playwright0.4.0然后所有人在统一版本下执行浏览器安装。遇到“我这边能跑你那边报错”的经典问题第一件事就是对比版本号而不是去猜代码逻辑。2.3 不会每天遇到但一旦遇到就很致命的环境问题第一类问题是 headless 模式下字体和渲染差异。无头模式没有系统的字体栈页面上某些中文字符显示成方块截图对比就会失败。解决方案是先给系统装中文字体或者把字体文件打进镜像。第二类是并行执行时的资源竞争。Playwright 默认每个 worker 独立但如果你在同一台机器上开太多并发Chromium 的内存占用会非常夸张。我一般按 CPU 核数的一半来设并发数并且给每个浏览器进程设置--disable-dev-shm-usage避免共享内存不足导致崩溃。第三类是 CI 中的网络访问限制。自动化测试如果需要访问外部资源比如测试环境里的 CDN或者页面里有第三方统计脚本网络策略一变整批用例就飘。这个要通过白名单而不是在代码里硬等到超时。3. 定位器和动态内容找到元素只是开始稳住元素才是本事3.1 语义定位器为什么比 XPath 更值得优先选择定位器是 UI 自动化的地基。第一版时代我写了很多 XPath当时觉得 xpath 最万能。后来发现万能的代价是脆弱——它必须依赖确切的 DOM 层次结构。前端工程师加一层 div脚本就“找不到元素”。Playwright 的定位器体系里我最常用的是 role、text 和 label。语义定位器不关心元素嵌套层级它关心的是“这个元素在页面上扮演什么角色”。from playwright.sync_api import sync_playwright with sync_playwright() as p: browser p.chromium.launch(headlessTrue) page browser.new_page() page.goto(https://example.com) search page.get_by_role(searchbox, name搜索) search.fill(Playwright) search.press(Enter) result page.get_by_text(第一个搜索结果) result.click() browser.close()get_by_role(searchbox)对应的是原生role属性或者 input 的语义类型。对于那些没有语义的 div我会退一步用page.locator(css)但只作为兜底方案。判断规则很简单优先用能表达业务含义的定位方式最后才用 DOM 路径。3.2 自动等待与动态渲染刚用 Playwright 时我还会习惯性写time.sleep(2)后来基本把它从代码里删光了。Playwright 有一套内置的 actionability 检查点击一个元素时它会自动等元素可见、稳定、接收事件。这个机制比 sleep 聪明得多也快得多。动态渲染最大的坑在于元素已经在 DOM 里但它可能还被 loading 状态遮挡着。比如列表页先渲染一个骨架屏再渲染真实数据。骨架屏和真实数据的标签都是 div你用locator(.item)可能匹配到还在加载中的空节点。我的处理方式是把“等待”从固定 sleep 改成条件断言from playwright.sync_api import expect # 等待列表出现最多等10秒 expect(page.locator(.data-table)).to_be_visible(timeout10000) # 等待某个请求返回而不是死等时间 with page.expect_response(**/api/list) as response_info: page.click(button[data-testidrefresh]) response response_info.value assert response.okexpect_response是我特别推荐的一种方式。它能等到接口真实返回比任何 sleep 都更贴近业务真实状态。当然它不是万能的如果接口返回 200 但数据还没渲染完还得结合可见性断言再等一下。3.3 iframe 与 Shadow DOM说说 iframe。现在不少后台管理系统都会用嵌套 iframe尤其是旧系统改造的项目主框架一个 iframe内容区又一个 iframe。常规的page.locator根本找不到 iframe 里的元素。Playwright 提供了frame_locator可以把定位范围直接切换到指定 frameframe page.frame_locator(#main-content-frame) submit_btn frame.get_by_role(button, name提交) submit_btn.click()这里有个容易踩的细节如果你只定位到 iframe 本身然后执行click()Playwright 会报错因为 iframe 标签本身在父级页面里但它的内容是另一个 document。frame_locator就是专门对付这种情况的它会自动处理 document 切换。Shadow DOM 则稍微麻烦一点。Playwright 默认的穿透能力比 Selenium 强大部分 open shadow DOM 可以直接用locator(css...)命中内部节点。但遇到 closed shadow DOM常规方式无能为力。我的建议是先通过page.evaluate检查该 shadow root 的 mode如果是 closed优先考虑与前端团队沟通加测试标记而不是写一段很复杂的 JS Hack 去强行穿透。4. 用例结构化设计让 AI 也能看懂你的脚本4.1 POM 的价值不只是“少写代码”Page Object Model我们叫它页面对象模型。很多团队把它当成一种“编码规范”但实际上它是维护自动化资产的关键投资。页面对象的核心思路是把页面元素和操作封装成对象用例层只表达“做什么”不表达“怎么定位”。比如登录页我通常会这样建模class LoginPage: def __init__(self, page): self.page page self.username_input page.get_by_label(用户名) self.password_input page.get_by_label(密码) self.login_button page.get_by_role(button, name登 录) def login(self, username: str, password: str): self.username_input.fill(username) self.password_input.fill(password) self.login_button.click() def get_error_message(self) - str: return self.page.locator(.error-tip).inner_text()用例层就很干净了def test_login_success(page): login_page LoginPage(page) login_page.login(tester, pass123) expect(page).to_have_title(首页)这样做的价值不只在少写重复代码。更重要的是当页面改动时你只需要改页面对象这一个文件而不是在几百个用例里逐个替换定位器。页面对象就像一层“契约”把底层 DOM 变化和业务用例隔离开。4.2 用例层与页面对象分离很多团队做坏 POM是因为他们把用例逻辑也塞进了页面对象。比如在 LoginPage 里写死测试数据、写断言、甚至处理异常分支。页面对象一旦开始“聪明”复用率就会下降。我的原则是页面对象只提供能力和状态不负责决策。业务链路的编排放在用例层数据准备放在 fixture 或独立的 factory 里。这样标记出的页面对象几乎是无状态的可以被任意用例安全复用。新项目里我还加了一层“人工可读”约束每一条测试用例的标题必须能讲清楚业务场景。比如test_user_can_reset_password_with_valid_email而不是test_002。这种命名习惯在传统手工用例里很常见但自动化团队经常忽略。可读的用例名对后续 AI Agent 分析日志、定位失败场景非常有帮助。4.3 数据和选择器的畸形耦合我见过最痛苦的自动化代码是把测试数据和选择器耦合在同一个元组里。比如# 反面案例 users [ (admin, 123456, page.get_by_role(button, name登录)), ]一旦某个系统提示文案变了你得去翻数据组一旦按钮文案变了又得去翻同一处。这两个维度的变化频率完全不一样耦合在一起维护成本直接翻倍。所以我坚持数据和定位分开。选择器永远放页面对象测试数据放 fixture 或配置文件执行结果放报告和日志。这样写出来的用例哪怕三个月后回头看上下文也能快速接上。这也是后面 AI 能介入生成脚本的前提——上下文清晰模型才有足够信息去生成合理的代码。5. MCP 和 Agent 落地实录当测试脚本开始自己“写”自己5.1 先搞清楚 Playwright MCP 和 CDP MCP 在研究什么最近“Playwright MCP”这个词很火很多人把它当成“AI 自动做 UI 测试”的银弹。其实 MCP 是模型上下文协议本质是让大模型通过一组工具去和外部环境交互。Playwright MCP 做的事情是把浏览器操作封装成模型可调用的工具比如打开页面、点击元素、读取文本、截图。Chrome DevTools MCP 则是另一条路子它直接对接 Chrome DevTools 协议模型可以拿到网络请求、性能指标、控制台日志。两者定位有重叠但侧重点不同。能力维度Playwright MCPChrome DevTools MCP主要视角自动化测试与页面操作浏览器调试与性能诊断典型动作跳转、点击、填表、截图抓网络、查 console、分析性能适用场景生成测试脚本、验证 UI排查前端问题、调试页面与脚本生成的关系直接产出可运行的测试代码提供细节数据辅助判断我自己的理解是如果你目标是生成 UI 测试用例优先考虑 Playwright MCP如果你要排查的是页面资源加载、接口请求异常CDP MCP 更对口。两者不是替代关系而是可以配合使用的关系。5.2 AI 辅助脚本生成的一个有效工作流我用 AI Agent 生成脚本不会只丢一句“帮我写个自动化脚本”。那样生成出来的代码看起来完整实则无法落到当前页面。因为我页面的业务逻辑和元素标记是独有的模型不知道。我现在的工作流是四步先人工熟悉页面再写页面对象的关键定位器再让 AI 生成用例编排最后用 trace 回放验证。具体来说我会先给模型提供这样一段上下文技术栈Python pytest Playwright。页面对象类名和已有的关键方法列表。业务场景的步骤描述例如“打开登录页 - 输入用户名密码 - 点击登录 - 验证首页标题”。测试环境地址和测试账号相关信息。然后让模型按这个模板生成用例层代码。这样做的好处是模型不需要凭空猜测定位器因为定位器在我已经写好的页面对象里它只需要按自然语言步骤把方法调用串起来。生成结果通常一次可用的概率很高。我也做过拿 langchain 去做更复杂的 Agent让模型读取测试用例文档后自动生成脚本。思路很新但目前落地效果还没有吹得那么玄幻。核心瓶颈在于测试用例文档本身表达不规范模型需要处理模糊语义而且定位器如果没沉淀到页面对象生成代码的脆弱率会很高。结论是AI 强在“把自然语言步骤变成代码结构”弱在“凭空知道你的 DOM 里有什么”。所以不要指望 AI 完全替代人而是把重复拼接工作交给 AI把页面对象地基自己打好。5.3 我在实际使用中碰到的真实边界实际跑下来我碰到三个边界。模型上下文长度。页面对象一多把所有类都塞进提示词既不现实也不经济。应对办法是只把与本次用例相关的页面对象文件内容和目录结构放进去。模型对业务状态的不敏感。它生成断言时经常会写成“断言存在某个文本”但实际页面上这个文本可能是异步出现的、甚至在多个页面存在。这类问题靠审查代码很难一眼发现必须靠跑一遍用例看失败现场。回放验证的必要性。我现在生成完脚本之后一定会做一个真实的 trace 回放而不是只跑 pytest 看绿。因为 pytest 通过只能说明没有报错不代表操作路径真的符合业务预期。打开 trace 看关键步骤的截图才敢确认“这个脚本真的有用”。6. 实战排障三个“玄学”失败和一套可复用的排查链路6.1 三个高频失败特征与根因定位项目跑久了你会发现失败的类型就那么几大类。我把最常见的三种整理成一个表格方便对照排查。失败现象常见根因排查方向元素定位到了但点击报 timeout元素被遮罩层遮挡或者正在动画中看失败截图检查有没有 loading 遮罩、cookie 弹窗、固定 Header 遮挡页面已经加载但断言失败接口返回后 DOM 渲染延迟早于数据插入使用 expect 轮询断言或监听目标接口返回后再断言用例在本地通过CI 上随机失败并发资源竞争、浏览器缓存不一致检查并行数和浏览器缓存尝试串行复现对比 trace很多人遇到第一类问题第一反应是加长 timeout。但 timeout 只能掩盖问题不能解决“元素真的被挡住”这个事实。正确做法是点击前先判断是什么东西挡住。最常见的是页面右下角弹出的隐私授权弹窗它把整层遮罩盖在页面上。我通常会在 fixture 里统一关闭这种弹窗而不是每个用例里各处理一次。6.2 排查链路与工具trace、codegen、慢动作Playwright 最舒服的一点是失败现场非常完整。只要打开 trace就能看到每个操作前的页面快照、操作中发送的请求、操作后的 DOM 变化甚至能看到定位器匹配到哪几个元素。这个能力比 Selenium 时代好用太多。开启 trace 很简单context browser.new_context( record_video_dirvideos/, ) context.tracing.start(screenshotsTrue, snapshotsTrue, sourcesTrue) # 执行你的用例代码 context.tracing.stop(pathtrace.zip)跑完以后直接用命令查看python -m playwright show-trace trace.zip如果是奇怪的上报问题用--headed模式跑一遍比看图效率高得多。我还会配合--slow-mo300让浏览器放慢动作200 毫秒的减速足够肉眼判断元素交互顺序是否符合预期。python -m playwright codegen --slow-mo 500 https://example.comcodegen 不只适合新手也适合老手快速确认元素定位方式。当你对着一个复杂组件怀疑“为什么我的定位器匹配不到”时打开 codegen 手动点一遍它会给出当前最可靠的定位器这比我凭记忆写选择器快得多。6.3 动态交互组件滑块等的合规测试思路最后说一个很多人会私信问的场景滑块验证码、图片拖动这类动态交互。这里先说清楚任何针对真实网站安全机制的绕过行为在合规性上都有极大问题我不支持也不应该在项目里去“过”这类风控系统。但如果你的目标是测试自己系统里的拖动组件或者在测试环境里有专门的滑动拼图组件需要覆盖那是完全正当的。关键是把这种交互当成普通的前端组件来处理用 Playwright 的鼠标事件模拟真实轨迹。box slider.bounding_box() page.mouse.move(box[x] 10, box[y] box[height] / 2) page.mouse.down() page.mouse.move(box[x] box[width] - 10, box[y] box[height] / 2, steps30) page.mouse.up()这里steps30的意思是让鼠标分 30 步移动过去而不是一次性瞬移。人类拖拽不会是瞬移的面对有行为检测的组件瞬移很容易直接失败。但这种做法依然只能用于你拥有测试权限的环境里切勿套用到第三方生产系统。排查这类问题我会先录 trace然后对比每次移动的坐标序列。因为拖拽类操作失败原因通常只有两类要么起点没按压到有效区域要么移动轨迹不符合判定条件。trace 里的鼠标轨迹视图可以一目了然看出问题出在哪一步。这一年多迭代下来我最深的感受是Playwright 这种工具已经把“写得出来”的难度降到很低真正的门槛在于“能不能稳定地写下去”。稳定靠的是合理定位策略、结构化页面对象、完整失败现场以及把 AI 当成提效工具而不是灵魂替代品。第二版写的这些内容基本就是我当前项目里每天都在用的方案希望对你有所借鉴。