Playwright 中 Page 对象的常用方法详解
Page 对象是 Playwright 的核心 API 之一,代表浏览器中的一个标签页或弹出窗口。以下是 Page 对象最常用的方法及其使用示例和运行原理。
1. 导航相关方法
goto(url)
作用:导航到指定 URL
原理:等待页面加载到网络空闲状态(load 事件触发)
await page.goto("https://example.com")
# 同步方式
page.goto("https://example.com")
reload()
作用:重新加载当前页面
原理:触发页面刷新,等待新页面加载完成
await page.reload()
# 可带选项
await page.reload(timeout=5000, wait_until="networkidle")
go_back()
/ go_forward()
作用:前进/后退导航
原理:模拟浏览器前进后退按钮行为
await page.go_back()
await page.go_forward()
2. 元素定位与交互
locator(selector)
作用:创建元素定位器
原理:返回一个 Locator 对象,不立即查询 DOM
button = page.locator("button.submit")
# 推荐使用更语义化的定位方式
button = page.get_by_role("button", name="Submit")
click(selector)
作用:点击指定元素
原理:执行可操作性检查后触发点击事件
await page.click("#submit-btn")
# 带选项
await page.click("button", force=True, timeout=5000)
fill(selector, value)
作用:填充表单字段
原理:先清除字段再输入值,触发适当事件
await page.fill("#username", "testuser")
type(selector, text)
作用:模拟键盘输入
原理:逐个字符触发键盘事件
await page.type("#search", "Playwright", delay=100) # 带输入延迟
3. 页面内容操作
evaluate(expression)
作用:在页面上下文中执行 JavaScript
原理:在浏览器环境中执行脚本并返回结果
title = await page.evaluate("document.title")
# 传参数
result = await page.evaluate("(arg) => window.myFunction(arg)", arg_value)
content()
作用:获取页面完整 HTML
原理:返回当前 DOM 的序列化 HTML
html = await page.content()
set_content(html)
作用:设置页面 HTML 内容
原理:替换当前文档内容,不触发网络请求
await page.set_content("<h1>Test Page</h1>")
4. 等待与断言
wait_for_selector(selector)
作用:等待元素出现
原理:轮询 DOM 直到元素存在
await page.wait_for_selector(".loading-spinner", state="hidden")
wait_for_event(event)
作用:等待特定事件
原理:监听页面事件,返回 Promise
async with page.expect_event("popup") as popup_info:
await page.click("#popup-link")
popup = await popup_info.value
wait_for_timeout(ms)
作用:强制等待
原理:不推荐使用,除非绝对必要
await page.wait_for_timeout(1000) # 等待1秒
5. 页面管理
screenshot()
作用:截取页面截图
原理:捕获当前视口或全屏
await page.screenshot(path="screenshot.png", full_page=True)
pdf()
作用:生成 PDF
原理:打印当前页面为 PDF(仅限 Chromium)
await page.pdf(path="output.pdf")
close()
作用:关闭页面
原理:触发页面卸载过程
await page.close()
6. 对话框处理
on(event, handler)
作用:监听对话框事件
原理:注册事件处理函数
page.on("dialog", lambda dialog: dialog.accept())
expect_dialog()
作用:等待对话框出现
原理:返回上下文管理器处理对话框
async with page.expect_dialog() as dialog_info:
await page.click("#trigger-alert")
dialog = await dialog_info.value
7. 框架处理
frame(name)
作用:获取指定 iframe
原理:返回 Frame 对象用于操作 iframe 内容
frame = page.frame("login-frame")
await frame.fill("#username", "admin")
8. 浏览器上下文
context
作用:获取所属浏览器上下文
原理:返回创建该页面的 BrowserContext
context = page.context
cookies = await context.cookies()
运行原理总结
- 自动等待:大多数操作会自动等待元素可操作
- 事件驱动:基于浏览器事件循环响应各种页面事件
- 智能重试:操作失败时会自动重试直到超时
- 沙盒环境:每个测试运行在独立环境中,互不影响
最佳实践示例
async def test_complete_flow(page):
# 导航
await page.goto("https://shop.example.com")
# 等待元素
await page.wait_for_selector("#products")
# 定位与交互
await page.get_by_role("link", name="Login").click()
await page.fill("#username", "testuser")
await page.fill("#password", "password123")
await page.click("#login-btn")
# 断言
await expect(page).to_have_url("https://shop.example.com/dashboard")
await expect(page.get_by_text("Welcome, testuser")).to_be_visible()
# 处理对话框
page.on("dialog", lambda dialog: dialog.accept())
await page.click("#logout-btn")
# 截图
await page.screenshot(path="after_login.png")
这些方法覆盖了 Page 对象 80% 以上的日常使用场景,掌握它们可以高效完成大多数 Web 自动化测试任务。