Playwright Page 类 API 参考
Page 是 Playwright 中最常用的类，提供页面交互的全部方法。
导航方法
| 方法 | 说明 |
|---|---|
page.goto(url, options?) | 导航到 URL |
page.goBack(options?) | 后退 |
page.goForward(options?) | 前进 |
page.reload(options?) | 刷新页面 |
定位器方法
| 方法 | 说明 |
|---|---|
page.getByRole(role, options?) | 按 ARIA 角色定位 |
page.getByText(text, options?) | 按文本内容定位 |
page.getByLabel(text, options?) | 按关联 label 定位 |
page.getByPlaceholder(text) | 按 placeholder 定位 |
page.getByAltText(text) | 按图片 alt 属性定位 |
page.getByTitle(text) | 按 title 属性定位 |
page.getByTestId(id) | 按 data-testid 定位 |
page.locator(selector) | CSS / XPath 定位 |
page.frameLocator(selector) | iframe 定位 |
页面属性获取
| 方法 | 说明 |
|---|---|
page.title() | 获取页面标题 |
page.url() | 获取当前 URL |
page.content() | 获取完整 HTML 内容 |
page.viewportSize() | 获取视口大小 |
截图与 PDF
| 方法 | 说明 |
|---|---|
page.screenshot(options?) | 页面截图 |
page.pdf(options?) | 生成 PDF（仅 Chromium） |
page.video() | 获取视频对象 |
键盘与鼠标
| 属性 | 说明 |
|---|---|
page.keyboard | Keyboard 对象 |
page.mouse | Mouse 对象 |
page.touchscreen | Touchscreen 对象 |
JS 执行
| 方法 | 说明 |
|---|---|
page.evaluate(fn, arg?) | 在页面上下文执行 JS |
page.evaluateHandle(fn, arg?) | 执行 JS 并返回 JSHandle |
page.addInitScript(script) | 注入初始化脚本 |
page.addStyleTag(options?) | 添加样式标签 |
page.addScriptTag(options?) | 添加脚本标签 |
page.exposeFunction(name, fn) | 向页面暴露函数 |
等待方法
| 方法 | 说明 |
|---|---|
page.waitForURL(url, options?) | 等待 URL 变化 |
page.waitForLoadState(state?) | 等待加载状态 |
page.waitForTimeout(ms) | 固定等待 |
page.waitForEvent(event, options?) | 等待事件 |
page.waitForResponse(urlOrPredicate, options?) | 等待网络响应 |
page.waitForRequest(urlOrPredicate, options?) | 等待网络请求 |
网络与路由
| 方法 | 说明 |
|---|---|
page.route(url, handler) | 拦截网络请求 |
page.unroute(url, handler?) | 取消拦截 |
page.routeFromHAR(har, options?) | 从 HAR 文件回放网络 |
事件
| 事件 | 说明 |
|---|---|
page.on('request', handler) | 监听请求 |
page.on('response', handler) | 监听响应 |
page.on('dialog', handler) | 监听弹窗 |
page.on('download', handler) | 监听下载 |
page.on('popup', handler) | 监听弹窗页面 |
page.on('console', handler) | 监听控制台 |
page.on('pageerror', handler) | 监听页面错误 |
page.on('close', handler) | 监听页面关闭 |
Frame 相关
| 方法 | 说明 |
|---|---|
page.mainFrame() | 获取主 Frame |
page.frames() | 获取所有 Frame |
其他
| 方法 | 说明 |
|---|---|
page.context() | 获取所属 BrowserContext |
page.close() | 关闭页面 |
page.pause() | 暂停执行（调试用） |
page.setViewportSize(size) | 设置视口大小 |
page.bringToFront() | 将页面置为前台 |
page.emulateMedia(options?) | 模拟媒体特性 |
page.clock | Clock 对象（时间模拟） |
PageAssertions（自动重试断言）
| 断言方法 | 说明 |
|---|---|
expect(page).toHaveTitle(title) | 页面标题断言 |
expect(page).toHaveURL(url) | 页面 URL 断言 |
expect(page).toHaveScreenshot(options?) | 页面截图对比 |