1. 项目概述为什么Page对象是Playwright的灵魂如果你刚开始用Playwright写自动化测试脚本可能会觉得它和Selenium很像——无非是启动浏览器、定位元素、点击输入。但当你真正深入使用特别是开始处理多标签页、弹窗、iframe这些复杂场景时就会意识到Playwright对“页面”这个概念的理解和抽象比传统工具要深刻得多。这个抽象的核心就是Page对象。在我过去十多年的自动化测试经验里见过太多因为对“页面”管理不善而导致的脚本脆弱、维护困难的问题。一个典型的例子是脚本在点击某个链接后新页面在新标签页打开但代码还在老页面上找元素结果当然是找不到。又或者页面上突然弹出一个模态对话框脚本却“视而不见”继续操作后面的元素导致后续步骤全部失败。Playwright的Page对象就是为了系统性地解决这些问题而设计的。它不仅仅是一个“当前标签页”的句柄更是一个完整的执行上下文封装了页面的生命周期、DOM状态、JavaScript执行环境、网络请求、对话框处理等一系列能力。理解Page是写出健壮、高效的Playwright自动化脚本的关键。这篇文章我们就来彻底拆解Playwright中的Page对象。无论你是刚入门的新手还是从Selenium转过来的老手相信都能从中获得新的启发和可以直接“抄作业”的实战技巧。2. Page对象的核心设计与架构思路2.1 Page vs BrowserContext vs Browser三层架构清晰分工很多新手容易混淆Browser、BrowserContext和Page这三个概念。你可以把它们理解为一个公司的三层架构Browser浏览器实例相当于公司的物理办公楼。启动一个Browser比如p.chromium.launch()就像租下了一栋楼这是最重量级的资源。一个Browser进程对应一个真实的浏览器可执行文件如Chrome。BrowserContext浏览器上下文相当于公司里的一个独立事业部。每个事业部有自己独立的会议室缓存、档案柜Cookies、LocalStorage和预算权限设置。它们共享办公楼的基础设施浏览器进程但业务和数据完全隔离。创建一个BrowserContextbrowser.new_context()非常轻量且快速是实现多用户、多会话测试的推荐方式。Page页面相当于事业部里的一个具体项目组。一个事业部可以同时开展多个项目即一个BrowserContext下可以有多个Page。每个Page对应浏览器中的一个标签页Tab。项目组在事业部的框架下运作共享事业部的资源如Cookies但专注于自己页面的具体任务。为什么要设计成这样主要是为了资源隔离和执行效率。资源隔离想象你要测试一个电商网站的用户A购物车和用户B购物车是否互不影响。如果用两个独立的Browser实例开销巨大。如果用两个Page但在同一个BrowserContext下它们会共享Cookies导致用户状态串扰。正确的做法是创建两个独立的BrowserContext每个里面再开一个Page。这样两个页面就拥有了完全独立的会话存储。执行效率创建一个新的BrowserContext比启动一个新的Browser快得多消耗的资源也少得多。在需要模拟多个独立环境的测试场景中这能显著提升执行速度。from playwright.sync_api import sync_playwright with sync_playwright() as p: # 1. 租下办公楼启动浏览器 browser p.chromium.launch(headlessFalse) # 2. 成立两个独立的事业部创建两个隔离的上下文 context_user1 browser.new_context() context_user2 browser.new_context() # 3. 在每个事业部里成立项目组打开页面 page_a context_user1.new_page() page_b context_user2.new_page() # page_a 和 page_b 拥有完全独立的Cookie、本地存储等 # 可以分别登录两个不同的账号互不干扰 # ... 执行测试操作 ... browser.close()2.2 Page的生命周期从诞生到消亡一个Page对象从创建到关闭会经历一系列明确的状态事件。理解这些事件对于编写稳定的脚本至关重要。创建new_page()或context.new_page()此时页面对象存在但标签页内容是空的about:blank。导航page.goto(url)这是最关键的阶段。Playwright会等待页面达到“加载完成”的状态。但请注意这里的“加载完成”不等于所有异步请求都结束。默认情况下goto会等待到load事件触发。对于现代单页应用SPA这通常不够我们后面会讲如何更精确地等待。活跃操作期页面加载后你可以进行各种操作点击、输入、获取元素等。页面内容可能通过JavaScript动态变化。页面跳转/新开点击一个链接可能导致当前页面导航到新URL同页跳转也可能在新标签页打开产生新的Page对象。Playwright提供了page.wait_for_event(‘popup’)来捕获新页面。关闭page.close()或上下文关闭页面被关闭。如果这个页面是某个BrowserContext下的最后一个页面关闭页面通常不会自动关闭上下文但关闭上下文会关闭其下的所有页面。一个关键的心得永远不要假设页面在你操作时处于稳定状态。现代Web应用大量使用异步加载。你的脚本在点击一个按钮后应该等待某个特定的、可见的结果出现例如一个加载完成的指示器消失或者某个期望的元素出现而不是盲目地time.sleep。3. Page核心操作与API深度解析3.1 导航与等待告别time.sleep的玄学导航是页面操作的起点。page.goto(url)是最常用的方法但它的默认行为可能不符合你的预期。# 基础用法 page.goto(https://example.com)问题来了goto什么时候算成功默认是等待到load事件。但对于一个后台还在拉取数据的SPA页面load事件触发时页面可能只是个空架子关键数据还没渲染出来。Playwright提供了更强大的等待机制# 方案1等待到某个特定元素出现这是最可靠的方式 page.goto(https://example.com) page.wait_for_selector(#main-content, statevisible) # 等待主要内容区域可见 # 方案2等待到“网络几乎空闲”适用于大多数动态加载页面 # wait_untilnetworkidle 会等待到至少500ms内没有超过2个网络连接 page.goto(https://example.com, wait_untilnetworkidle) # 方案3组合等待策略推荐 page.goto(https://example.com, wait_untildomcontentloaded) # 先等DOM解析完 # 然后等待你关心的特定元素 page.wait_for_selector(.data-table tbody tr, stateattached) # 再等待这个元素内部的数据加载完成例如等待“加载中”的spinner消失 page.wait_for_selector(.loading-spinner, statehidden)wait_until参数详解commit当网络响应开始收到HTTP头时就返回。太快基本不用。domcontentloaded当HTML文档的DOM完全加载和解析后触发不等待样式表、图片等。速度较快。load默认等待load事件触发。页面所有资源如图片加载完毕。networkidle等待到至少500ms内没有超过2个网络连接。对于SPA非常有用但注意一些长轮询或WebSocket连接可能导致永远等不到。实操心得我个人的最佳实践是组合使用。先用page.goto(url, wait_until“domcontentloaded”)快速获取到基础DOM然后立即用page.wait_for_selector()等待一个关键的、最终会出现的业务元素。这个元素应该是用户能感知到的页面“就绪”的标志。避免使用networkidle作为唯一等待条件因为一些后台心跳请求会阻止它达成。3.2 元素定位与交互比Selenium更优雅的写法Playwright的定位器LocatorAPI是其一大亮点。它采用链式调用非常符合直觉。# 传统方式先定位再操作 search_box page.locator(input[nameq]) search_box.fill(Playwright) search_box.press(Enter) # 链式调用更简洁 page.locator(input[nameq]).fill(Playwright).press(Enter)定位策略的精髓Playwright鼓励使用面向用户的定位器。什么意思就是尽量用用户看得见的内容来定位而不是脆弱的内部ID或复杂的CSS路径。# 不推荐依赖可能变化的内部ID或复杂结构 page.click(#submit-button-12345) page.click(div.container div.form button:nth-child(3)) # 推荐使用文本内容、角色、可访问性属性 page.click(text登录) # 点击包含“登录”文本的元素 page.click(button:has-text(确认提交)) # 点击按钮且按钮包含“确认提交”文本 page.click([aria-label搜索]) # 点击具有特定aria-label的元素 page.click(input[placeholder请输入用户名]) # 通过占位符定位为什么这样更好前端代码重构时ID和CSS结构很容易改变但按钮的文本、给屏幕阅读器使用的aria-label、输入框的placeholder这些面向用户的属性相对稳定得多。这能极大提升自动化脚本的健壮性。处理动态内容与列表# 等待一个动态出现的列表项 page.wait_for_selector(.todo-list li) # 获取列表所有项 items page.locator(.todo-list li).all() print(f找到 {len(items)} 个待办事项) # 对列表中的每一项进行操作例如点击第三个 page.locator(.todo-list li).nth(2).click() # nth是从0开始的 # 更强大的使用filter根据内部文本过滤 completed_items page.locator(.todo-list li).filter(has_text已完成)3.3 处理多页面、弹窗和框架这是Page对象真正发挥威力的地方。处理新标签页Popup# 在点击可能打开新标签页的链接前先监听‘popup’事件 with page.expect_popup() as popup_info: page.click(a[target_blank]) # 点击一个 target_blank 的链接 new_page popup_info.value # 获取新页面的Page对象 # 现在可以在新页面上操作了 new_page.wait_for_load_state() print(new_page.title()) # ... 对新页面进行操作 ... new_page.close() # 操作完后关闭它处理JavaScript对话框alert, confirm, prompt在Selenium里处理这些弹窗比较麻烦。Playwright则可以在弹窗出现前就“预定”好如何处理它。# 方法1在动作发生前先定义对话框处理逻辑 page.once(dialog, lambda dialog: dialog.accept()) # 下次出现对话框时自动接受 page.click(button#delete) # 点击会触发 confirm(确定删除) 的按钮 # 方法2使用 expect_event 更精确地等待和处理 page.on(dialog, lambda dialog: dialog.accept()) # 监听所有对话框并接受 # 或者获取对话框消息 def handle_dialog(dialog): print(f对话框消息{dialog.message}) dialog.dismiss() # 取消 page.on(dialog, handle_dialog)处理iframe内嵌框架iframe是一个独立的文档你需要先定位到iframe元素然后获取其内部的Frame对象可以近似理解为子Page。# 通过iframe的name或URL定位 frame page.frame(namelogin-frame) # 通过name # 或 frame page.frame(urlr.*/login\.html) # 通过URL正则匹配 # 如果通过元素定位 iframe_element page.locator(iframe#the-iframe) frame iframe_element.content_frame() # 在frame内部操作 frame.fill(#username, myuser) frame.click(#submit)避坑指南一个常见的错误是在父页面定位不到元素时没意识到元素在iframe里。当你用常规选择器找不到元素时第一反应应该是检查页面结构里是否有iframe。另外有些iframe是动态加载的记得先page.wait_for_selector(“iframe”)。4. 高级特性与实战技巧4.1 网络请求拦截与模拟MockPlaywright允许你在页面级别拦截和修改任何网络请求这对于测试和调试是无价之宝。# 1. 路由Route拦截请求并返回自定义响应 from playwright.sync_api import sync_playwright def handle_route(route): # 拦截对特定API的请求返回模拟数据 if /api/user/profile in route.request.url: route.fulfill( status200, content_typeapplication/json, body{name: Mock User, age: 30} ) else: # 其他请求继续正常进行 route.continue_() with sync_playwright() as p: browser p.chromium.launch(headlessFalse) page browser.new_page() # 启用请求拦截 page.route(**/*, handle_route) # **/* 匹配所有请求 page.goto(https://your-app.com) # 此时页面中请求 /api/user/profile 将收到我们模拟的数据 # 测试完成后取消路由 page.unroute(**/*, handle_route)这个功能可以用来屏蔽第三方资源如广告、分析脚本以加速测试。模拟API返回测试前端在不同数据下的表现。注入测试脚本。验证请求是否按预期发出断言请求的URL、方法、载荷。4.2 执行JavaScript代码虽然Playwright的API已经很强大了但有时直接执行JS更直接。# 在页面上下文中执行JS并获取返回值 dimensions page.evaluate(() { return { width: document.documentElement.clientWidth, height: document.documentElement.clientHeight, deviceScaleFactor: window.devicePixelRatio }; }) print(dimensions) # 将Python变量传入JS上下文 selector .item count page.evaluate(selector document.querySelectorAll(selector).length, selector) print(f找到 {count} 个 .item 元素) # 在元素句柄上执行JS element page.locator(#myElement).first bounding_box element.evaluate(node node.getBoundingClientRect())什么时候用evaluate获取无法通过Playwright API直接获取的DOM属性或计算样式。执行复杂的DOM操作虽然Playwright API通常已覆盖。调用页面内定义的JavaScript函数。性能测量或获取浏览器环境信息。4.3 页面状态管理Cookies、LocalStorage与截图Cookies和本地存储# 1. 获取所有cookies cookies page.context.cookies() print(cookies) # 2. 设置cookies常用于登录状态保持 page.context.add_cookies([{ name: session_id, value: abc123, url: https://example.com, # 或使用 domain }]) # 3. 清除cookies page.context.clear_cookies() # 4. 操作LocalStorage (通过evaluate) page.evaluate(() localStorage.setItem(theme, dark)) theme page.evaluate(() localStorage.getItem(theme))截图与录屏# 截取可视区域 page.screenshot(pathscreenshot.png) # 截取完整页面长截图 page.screenshot(pathfullpage.png, full_pageTrue) # 对特定元素截图 page.locator(.header).screenshot(pathheader.png) # 录屏需要以非无头模式启动浏览器并指定录屏路径 context browser.new_context(record_video_dir./videos/) page context.new_page() # ... 你的操作 ... context.close() # 关闭上下文后视频文件会自动保存5. 常见问题排查与调试技巧实录即使理解了所有API实际编写脚本时还是会踩坑。下面是我总结的一些高频问题和解决方法。5.1 元素找不到TimeoutError这是最常见的问题。错误信息通常是Timeout 30000ms exceeded。排查清单等待是否充分这是首要原因。在操作元素前确保它已经出现在DOM中并且是可见的。不要用time.sleep用page.wait_for_selector。# 错误示范 page.click(#submit) time.sleep(5) # 玄学等待可能不够或浪费 page.locator(.success-message) # 正确示范 page.click(#submit) page.wait_for_selector(.success-message, statevisible, timeout10000)选择器是否正确打开浏览器开发者工具F12在Console里用document.querySelector(‘你的选择器’)测试一下看能否找到元素。Playwright也支持大部分CSS和XPath选择器。元素是否在iframe或Shadow DOM里如果在主文档里找不到检查是否嵌套在iframe里或者是否属于Shadow DOM。对于Shadow DOM需要使用或/deep/选择器Playwright支持page.locator(‘component::part(part-name)’)或page.locator(‘…’).shadow_root等语法。页面是否发生了导航点击后页面跳转了原来的page对象上下文已经变了。确保你在正确的页面对象上操作。如果是新开页用expect_popup捕获。是否有模态框遮挡检查页面上是否有alert,confirm, 或者一个全屏的loading遮罩层挡住了你的目标元素。需要先处理掉这些遮挡物。5.2 脚本在无头模式下运行失败但有头模式下正常无头模式headlessTrue和有头模式在某些细节上可能有差异。视口大小无头模式默认视口是800x600而有头模式是你屏幕的大小。某些响应式布局可能在不同尺寸下表现不同。解决方案始终显式设置视口大小。context browser.new_context(viewport{width: 1920, height: 1080}) page context.new_page()媒体查询或特性检测有些网站会检测navigator.webdriver属性来判断是否是自动化工具。Playwright默认会尝试隐藏这些特征但可能不完美。可以尝试添加更多启动参数browser p.chromium.launch(headlessFalse, args[ --disable-blink-featuresAutomationControlled ])动画或过渡效果有头模式下你能看到动画完成无头模式下可能太快导致脚本在动画中途就去点击元素。使用wait_for_selector的state参数并确保等待到元素处于最终状态如visible,enabled。5.3 性能优化与最佳实践重用BrowserContext如前所述创建BrowserContext比创建Browser快。在测试套件级别启动一个Browser在每个测试用例中创建独立的BrowserContext这是最佳实践。并行执行Playwright原生支持并行。利用BrowserContext的隔离性可以在一个Browser实例下创建多个BrowserContext每个运行在不同的线程或进程中执行独立的测试用例。避免不必要的导航如果测试不依赖完整的页面加载考虑直接通过page.set_content(html)设置页面内容或者使用page.route拦截请求并返回模拟数据这比访问真实网络快几个数量级。关闭资源养成好习惯显式关闭Page和BrowserContext。虽然Python的垃圾回收最终会做这件事但显式关闭可以立即释放资源如内存、端口。try: page context.new_page() # ... 你的测试 ... finally: page.close() context.close()5.4 调试利器Playwright Inspector与Trace ViewerPlaywright Inspector 在运行脚本时添加环境变量PWDEBUG1或者使用playwright codegen命令会打开一个交互式调试工具。你可以实时查看脚本执行。暂停执行检查页面状态。生成定位器代码。Trace Viewer 这是Playwright的“黑匣子”。在测试失败时它能回放整个操作过程。# 在创建上下文时启用trace记录 context browser.new_context() context.tracing.start(screenshotsTrue, snapshotsTrue, sourcesTrue) # ... 运行测试 ... # 测试结束后无论成功失败保存trace文件 context.tracing.stop(path “trace.zip”)用命令playwright show-trace trace.zip打开这个文件你可以一步步回看所有操作、网络请求、控制台日志和当时的页面快照。这对于在CI/CD环境中调试失败的测试用例极其有用。最后关于Page对象我个人最深的体会是把它看作一个智能的、可编程的用户而不仅仅是一个浏览器标签页的遥控器。你需要告诉它“等待这个条件成立后再点击”而不是“等2秒后点击”。你需要管理好它的“工作环境”Context和“任务清单”多个Page。当你以这种思维去编写脚本时写出来的自动化代码会稳定、清晰得多。
1. 项目概述为什么Page对象是Playwright的灵魂如果你刚开始用Playwright写自动化测试脚本可能会觉得它和Selenium很像——无非是启动浏览器、定位元素、点击输入。但当你真正深入使用特别是开始处理多标签页、弹窗、iframe这些复杂场景时就会意识到Playwright对“页面”这个概念的理解和抽象比传统工具要深刻得多。这个抽象的核心就是Page对象。在我过去十多年的自动化测试经验里见过太多因为对“页面”管理不善而导致的脚本脆弱、维护困难的问题。一个典型的例子是脚本在点击某个链接后新页面在新标签页打开但代码还在老页面上找元素结果当然是找不到。又或者页面上突然弹出一个模态对话框脚本却“视而不见”继续操作后面的元素导致后续步骤全部失败。Playwright的Page对象就是为了系统性地解决这些问题而设计的。它不仅仅是一个“当前标签页”的句柄更是一个完整的执行上下文封装了页面的生命周期、DOM状态、JavaScript执行环境、网络请求、对话框处理等一系列能力。理解Page是写出健壮、高效的Playwright自动化脚本的关键。这篇文章我们就来彻底拆解Playwright中的Page对象。无论你是刚入门的新手还是从Selenium转过来的老手相信都能从中获得新的启发和可以直接“抄作业”的实战技巧。2. Page对象的核心设计与架构思路2.1 Page vs BrowserContext vs Browser三层架构清晰分工很多新手容易混淆Browser、BrowserContext和Page这三个概念。你可以把它们理解为一个公司的三层架构Browser浏览器实例相当于公司的物理办公楼。启动一个Browser比如p.chromium.launch()就像租下了一栋楼这是最重量级的资源。一个Browser进程对应一个真实的浏览器可执行文件如Chrome。BrowserContext浏览器上下文相当于公司里的一个独立事业部。每个事业部有自己独立的会议室缓存、档案柜Cookies、LocalStorage和预算权限设置。它们共享办公楼的基础设施浏览器进程但业务和数据完全隔离。创建一个BrowserContextbrowser.new_context()非常轻量且快速是实现多用户、多会话测试的推荐方式。Page页面相当于事业部里的一个具体项目组。一个事业部可以同时开展多个项目即一个BrowserContext下可以有多个Page。每个Page对应浏览器中的一个标签页Tab。项目组在事业部的框架下运作共享事业部的资源如Cookies但专注于自己页面的具体任务。为什么要设计成这样主要是为了资源隔离和执行效率。资源隔离想象你要测试一个电商网站的用户A购物车和用户B购物车是否互不影响。如果用两个独立的Browser实例开销巨大。如果用两个Page但在同一个BrowserContext下它们会共享Cookies导致用户状态串扰。正确的做法是创建两个独立的BrowserContext每个里面再开一个Page。这样两个页面就拥有了完全独立的会话存储。执行效率创建一个新的BrowserContext比启动一个新的Browser快得多消耗的资源也少得多。在需要模拟多个独立环境的测试场景中这能显著提升执行速度。from playwright.sync_api import sync_playwright with sync_playwright() as p: # 1. 租下办公楼启动浏览器 browser p.chromium.launch(headlessFalse) # 2. 成立两个独立的事业部创建两个隔离的上下文 context_user1 browser.new_context() context_user2 browser.new_context() # 3. 在每个事业部里成立项目组打开页面 page_a context_user1.new_page() page_b context_user2.new_page() # page_a 和 page_b 拥有完全独立的Cookie、本地存储等 # 可以分别登录两个不同的账号互不干扰 # ... 执行测试操作 ... browser.close()2.2 Page的生命周期从诞生到消亡一个Page对象从创建到关闭会经历一系列明确的状态事件。理解这些事件对于编写稳定的脚本至关重要。创建new_page()或context.new_page()此时页面对象存在但标签页内容是空的about:blank。导航page.goto(url)这是最关键的阶段。Playwright会等待页面达到“加载完成”的状态。但请注意这里的“加载完成”不等于所有异步请求都结束。默认情况下goto会等待到load事件触发。对于现代单页应用SPA这通常不够我们后面会讲如何更精确地等待。活跃操作期页面加载后你可以进行各种操作点击、输入、获取元素等。页面内容可能通过JavaScript动态变化。页面跳转/新开点击一个链接可能导致当前页面导航到新URL同页跳转也可能在新标签页打开产生新的Page对象。Playwright提供了page.wait_for_event(‘popup’)来捕获新页面。关闭page.close()或上下文关闭页面被关闭。如果这个页面是某个BrowserContext下的最后一个页面关闭页面通常不会自动关闭上下文但关闭上下文会关闭其下的所有页面。一个关键的心得永远不要假设页面在你操作时处于稳定状态。现代Web应用大量使用异步加载。你的脚本在点击一个按钮后应该等待某个特定的、可见的结果出现例如一个加载完成的指示器消失或者某个期望的元素出现而不是盲目地time.sleep。3. Page核心操作与API深度解析3.1 导航与等待告别time.sleep的玄学导航是页面操作的起点。page.goto(url)是最常用的方法但它的默认行为可能不符合你的预期。# 基础用法 page.goto(https://example.com)问题来了goto什么时候算成功默认是等待到load事件。但对于一个后台还在拉取数据的SPA页面load事件触发时页面可能只是个空架子关键数据还没渲染出来。Playwright提供了更强大的等待机制# 方案1等待到某个特定元素出现这是最可靠的方式 page.goto(https://example.com) page.wait_for_selector(#main-content, statevisible) # 等待主要内容区域可见 # 方案2等待到“网络几乎空闲”适用于大多数动态加载页面 # wait_untilnetworkidle 会等待到至少500ms内没有超过2个网络连接 page.goto(https://example.com, wait_untilnetworkidle) # 方案3组合等待策略推荐 page.goto(https://example.com, wait_untildomcontentloaded) # 先等DOM解析完 # 然后等待你关心的特定元素 page.wait_for_selector(.data-table tbody tr, stateattached) # 再等待这个元素内部的数据加载完成例如等待“加载中”的spinner消失 page.wait_for_selector(.loading-spinner, statehidden)wait_until参数详解commit当网络响应开始收到HTTP头时就返回。太快基本不用。domcontentloaded当HTML文档的DOM完全加载和解析后触发不等待样式表、图片等。速度较快。load默认等待load事件触发。页面所有资源如图片加载完毕。networkidle等待到至少500ms内没有超过2个网络连接。对于SPA非常有用但注意一些长轮询或WebSocket连接可能导致永远等不到。实操心得我个人的最佳实践是组合使用。先用page.goto(url, wait_until“domcontentloaded”)快速获取到基础DOM然后立即用page.wait_for_selector()等待一个关键的、最终会出现的业务元素。这个元素应该是用户能感知到的页面“就绪”的标志。避免使用networkidle作为唯一等待条件因为一些后台心跳请求会阻止它达成。3.2 元素定位与交互比Selenium更优雅的写法Playwright的定位器LocatorAPI是其一大亮点。它采用链式调用非常符合直觉。# 传统方式先定位再操作 search_box page.locator(input[nameq]) search_box.fill(Playwright) search_box.press(Enter) # 链式调用更简洁 page.locator(input[nameq]).fill(Playwright).press(Enter)定位策略的精髓Playwright鼓励使用面向用户的定位器。什么意思就是尽量用用户看得见的内容来定位而不是脆弱的内部ID或复杂的CSS路径。# 不推荐依赖可能变化的内部ID或复杂结构 page.click(#submit-button-12345) page.click(div.container div.form button:nth-child(3)) # 推荐使用文本内容、角色、可访问性属性 page.click(text登录) # 点击包含“登录”文本的元素 page.click(button:has-text(确认提交)) # 点击按钮且按钮包含“确认提交”文本 page.click([aria-label搜索]) # 点击具有特定aria-label的元素 page.click(input[placeholder请输入用户名]) # 通过占位符定位为什么这样更好前端代码重构时ID和CSS结构很容易改变但按钮的文本、给屏幕阅读器使用的aria-label、输入框的placeholder这些面向用户的属性相对稳定得多。这能极大提升自动化脚本的健壮性。处理动态内容与列表# 等待一个动态出现的列表项 page.wait_for_selector(.todo-list li) # 获取列表所有项 items page.locator(.todo-list li).all() print(f找到 {len(items)} 个待办事项) # 对列表中的每一项进行操作例如点击第三个 page.locator(.todo-list li).nth(2).click() # nth是从0开始的 # 更强大的使用filter根据内部文本过滤 completed_items page.locator(.todo-list li).filter(has_text已完成)3.3 处理多页面、弹窗和框架这是Page对象真正发挥威力的地方。处理新标签页Popup# 在点击可能打开新标签页的链接前先监听‘popup’事件 with page.expect_popup() as popup_info: page.click(a[target_blank]) # 点击一个 target_blank 的链接 new_page popup_info.value # 获取新页面的Page对象 # 现在可以在新页面上操作了 new_page.wait_for_load_state() print(new_page.title()) # ... 对新页面进行操作 ... new_page.close() # 操作完后关闭它处理JavaScript对话框alert, confirm, prompt在Selenium里处理这些弹窗比较麻烦。Playwright则可以在弹窗出现前就“预定”好如何处理它。# 方法1在动作发生前先定义对话框处理逻辑 page.once(dialog, lambda dialog: dialog.accept()) # 下次出现对话框时自动接受 page.click(button#delete) # 点击会触发 confirm(确定删除) 的按钮 # 方法2使用 expect_event 更精确地等待和处理 page.on(dialog, lambda dialog: dialog.accept()) # 监听所有对话框并接受 # 或者获取对话框消息 def handle_dialog(dialog): print(f对话框消息{dialog.message}) dialog.dismiss() # 取消 page.on(dialog, handle_dialog)处理iframe内嵌框架iframe是一个独立的文档你需要先定位到iframe元素然后获取其内部的Frame对象可以近似理解为子Page。# 通过iframe的name或URL定位 frame page.frame(namelogin-frame) # 通过name # 或 frame page.frame(urlr.*/login\.html) # 通过URL正则匹配 # 如果通过元素定位 iframe_element page.locator(iframe#the-iframe) frame iframe_element.content_frame() # 在frame内部操作 frame.fill(#username, myuser) frame.click(#submit)避坑指南一个常见的错误是在父页面定位不到元素时没意识到元素在iframe里。当你用常规选择器找不到元素时第一反应应该是检查页面结构里是否有iframe。另外有些iframe是动态加载的记得先page.wait_for_selector(“iframe”)。4. 高级特性与实战技巧4.1 网络请求拦截与模拟MockPlaywright允许你在页面级别拦截和修改任何网络请求这对于测试和调试是无价之宝。# 1. 路由Route拦截请求并返回自定义响应 from playwright.sync_api import sync_playwright def handle_route(route): # 拦截对特定API的请求返回模拟数据 if /api/user/profile in route.request.url: route.fulfill( status200, content_typeapplication/json, body{name: Mock User, age: 30} ) else: # 其他请求继续正常进行 route.continue_() with sync_playwright() as p: browser p.chromium.launch(headlessFalse) page browser.new_page() # 启用请求拦截 page.route(**/*, handle_route) # **/* 匹配所有请求 page.goto(https://your-app.com) # 此时页面中请求 /api/user/profile 将收到我们模拟的数据 # 测试完成后取消路由 page.unroute(**/*, handle_route)这个功能可以用来屏蔽第三方资源如广告、分析脚本以加速测试。模拟API返回测试前端在不同数据下的表现。注入测试脚本。验证请求是否按预期发出断言请求的URL、方法、载荷。4.2 执行JavaScript代码虽然Playwright的API已经很强大了但有时直接执行JS更直接。# 在页面上下文中执行JS并获取返回值 dimensions page.evaluate(() { return { width: document.documentElement.clientWidth, height: document.documentElement.clientHeight, deviceScaleFactor: window.devicePixelRatio }; }) print(dimensions) # 将Python变量传入JS上下文 selector .item count page.evaluate(selector document.querySelectorAll(selector).length, selector) print(f找到 {count} 个 .item 元素) # 在元素句柄上执行JS element page.locator(#myElement).first bounding_box element.evaluate(node node.getBoundingClientRect())什么时候用evaluate获取无法通过Playwright API直接获取的DOM属性或计算样式。执行复杂的DOM操作虽然Playwright API通常已覆盖。调用页面内定义的JavaScript函数。性能测量或获取浏览器环境信息。4.3 页面状态管理Cookies、LocalStorage与截图Cookies和本地存储# 1. 获取所有cookies cookies page.context.cookies() print(cookies) # 2. 设置cookies常用于登录状态保持 page.context.add_cookies([{ name: session_id, value: abc123, url: https://example.com, # 或使用 domain }]) # 3. 清除cookies page.context.clear_cookies() # 4. 操作LocalStorage (通过evaluate) page.evaluate(() localStorage.setItem(theme, dark)) theme page.evaluate(() localStorage.getItem(theme))截图与录屏# 截取可视区域 page.screenshot(pathscreenshot.png) # 截取完整页面长截图 page.screenshot(pathfullpage.png, full_pageTrue) # 对特定元素截图 page.locator(.header).screenshot(pathheader.png) # 录屏需要以非无头模式启动浏览器并指定录屏路径 context browser.new_context(record_video_dir./videos/) page context.new_page() # ... 你的操作 ... context.close() # 关闭上下文后视频文件会自动保存5. 常见问题排查与调试技巧实录即使理解了所有API实际编写脚本时还是会踩坑。下面是我总结的一些高频问题和解决方法。5.1 元素找不到TimeoutError这是最常见的问题。错误信息通常是Timeout 30000ms exceeded。排查清单等待是否充分这是首要原因。在操作元素前确保它已经出现在DOM中并且是可见的。不要用time.sleep用page.wait_for_selector。# 错误示范 page.click(#submit) time.sleep(5) # 玄学等待可能不够或浪费 page.locator(.success-message) # 正确示范 page.click(#submit) page.wait_for_selector(.success-message, statevisible, timeout10000)选择器是否正确打开浏览器开发者工具F12在Console里用document.querySelector(‘你的选择器’)测试一下看能否找到元素。Playwright也支持大部分CSS和XPath选择器。元素是否在iframe或Shadow DOM里如果在主文档里找不到检查是否嵌套在iframe里或者是否属于Shadow DOM。对于Shadow DOM需要使用或/deep/选择器Playwright支持page.locator(‘component::part(part-name)’)或page.locator(‘…’).shadow_root等语法。页面是否发生了导航点击后页面跳转了原来的page对象上下文已经变了。确保你在正确的页面对象上操作。如果是新开页用expect_popup捕获。是否有模态框遮挡检查页面上是否有alert,confirm, 或者一个全屏的loading遮罩层挡住了你的目标元素。需要先处理掉这些遮挡物。5.2 脚本在无头模式下运行失败但有头模式下正常无头模式headlessTrue和有头模式在某些细节上可能有差异。视口大小无头模式默认视口是800x600而有头模式是你屏幕的大小。某些响应式布局可能在不同尺寸下表现不同。解决方案始终显式设置视口大小。context browser.new_context(viewport{width: 1920, height: 1080}) page context.new_page()媒体查询或特性检测有些网站会检测navigator.webdriver属性来判断是否是自动化工具。Playwright默认会尝试隐藏这些特征但可能不完美。可以尝试添加更多启动参数browser p.chromium.launch(headlessFalse, args[ --disable-blink-featuresAutomationControlled ])动画或过渡效果有头模式下你能看到动画完成无头模式下可能太快导致脚本在动画中途就去点击元素。使用wait_for_selector的state参数并确保等待到元素处于最终状态如visible,enabled。5.3 性能优化与最佳实践重用BrowserContext如前所述创建BrowserContext比创建Browser快。在测试套件级别启动一个Browser在每个测试用例中创建独立的BrowserContext这是最佳实践。并行执行Playwright原生支持并行。利用BrowserContext的隔离性可以在一个Browser实例下创建多个BrowserContext每个运行在不同的线程或进程中执行独立的测试用例。避免不必要的导航如果测试不依赖完整的页面加载考虑直接通过page.set_content(html)设置页面内容或者使用page.route拦截请求并返回模拟数据这比访问真实网络快几个数量级。关闭资源养成好习惯显式关闭Page和BrowserContext。虽然Python的垃圾回收最终会做这件事但显式关闭可以立即释放资源如内存、端口。try: page context.new_page() # ... 你的测试 ... finally: page.close() context.close()5.4 调试利器Playwright Inspector与Trace ViewerPlaywright Inspector 在运行脚本时添加环境变量PWDEBUG1或者使用playwright codegen命令会打开一个交互式调试工具。你可以实时查看脚本执行。暂停执行检查页面状态。生成定位器代码。Trace Viewer 这是Playwright的“黑匣子”。在测试失败时它能回放整个操作过程。# 在创建上下文时启用trace记录 context browser.new_context() context.tracing.start(screenshotsTrue, snapshotsTrue, sourcesTrue) # ... 运行测试 ... # 测试结束后无论成功失败保存trace文件 context.tracing.stop(path “trace.zip”)用命令playwright show-trace trace.zip打开这个文件你可以一步步回看所有操作、网络请求、控制台日志和当时的页面快照。这对于在CI/CD环境中调试失败的测试用例极其有用。最后关于Page对象我个人最深的体会是把它看作一个智能的、可编程的用户而不仅仅是一个浏览器标签页的遥控器。你需要告诉它“等待这个条件成立后再点击”而不是“等2秒后点击”。你需要管理好它的“工作环境”Context和“任务清单”多个Page。当你以这种思维去编写脚本时写出来的自动化代码会稳定、清晰得多。
)
