Browser

extends: EventEmitter

Browser 是通过 browserType.launch([options]) 创建的。下面是使用 Browser 创建 Page 的示例：

const { firefox } = require('playwright');  // Or 'chromium' or 'webkit'.

(async () => {
  const browser = await firefox.launch();
  const page = await browser.newPage();
  await page.goto('https://example.com');
  await browser.close();
})();

browser.on('disconnected')

Added in: v1.8

type: <Browser>

当 Browser 从浏览器应用程序断开连接时触发。这可能是由于以下原因之一发生的：

浏览器应用程序已关闭或崩溃。
调用了 browser.close() 方法。

browser.browserType()

Added in: v1.23

returns: <BrowserType>#

获取浏览器所属的浏览器类型（chromium、firefox 或 webkit）。

browser.close()

Added in: v1.8

returns: <Promise<void>>#

如果此浏览器是使用 browserType.launch([options]) 获取的，则关闭浏览器及其所有页面（如果已打开）。

如果连接到了此浏览器，则清除属于此浏览器的所有创建的上下文，并断开与浏览器服务器的连接。

note

这类似于强制退出浏览器。因此，在调用 browser.close() 之前，应该对之前使用 browser.newContext([options]) 显式创建的任何 BrowserContext 调用 browserContext.close()。

Browser 对象本身被视为已销毁，不能再使用。

browser.contexts()

Added in: v1.8

returns: <Array<BrowserContext>>#

返回所有打开的浏览器上下文的数组。在新创建的浏览器中，这将返回零个浏览器上下文。

const browser = await pw.webkit.launch();
console.log(browser.contexts().length); // prints `0`

const context = await browser.newContext();
console.log(browser.contexts().length); // prints `1`

browser.isConnected()

Added in: v1.8

returns: <boolean>#

指示浏览器是否已连接。

browser.newBrowserCDPSession()

Added in: v1.11

returns: <Promise<CDPSession>>#

note

CDP 会话仅在基于 Chromium 的浏览器上受支持。

返回新创建的浏览器会话。

browser.newContext([options])

Added in: v1.8

options? <Object>
- acceptDownloads? <boolean> 是否自动下载所有附件。默认为 true，接受所有下载。#
- baseURL? <string> 当使用 page.goto(url[, options])、page.route(url, handler[, options])、page.waitForURL(url[, options])、page.waitForRequest(urlOrPredicate[, options]) 或 page.waitForResponse(urlOrPredicate[, options]) 时，通过使用 URL() 构造函数构建相应的 URL 来考虑基本 URL。示例：#
  - baseURL: http://localhost:3000 并且导航到 /bar.html 结果为 http://localhost:3000/bar.html
  - baseURL: http://localhost:3000/foo/ 并且导航到 ./bar.html 结果为 http://localhost:3000/foo/bar.html
  - baseURL: http://localhost:3000/foo (没有尾随斜杠) 并且导航到 ./bar.html 结果为 http://localhost:3000/bar.html
- bypassCSP? <boolean> 切换绕过页面的 Content-Security-Policy。#
- colorScheme? <"light"|"dark"|"no-preference"> 模拟 'prefers-colors-scheme' 媒体特性，支持的值为 'light'、'dark'、'no-preference'。有关详细信息，请参阅 page.emulateMedia([options])。默认为 'light'。#
- deviceScaleFactor? <number> 指定设备缩放因子（可以认为是 dpr）。默认为 1。#
- extraHTTPHeaders? <Object<string, string>> 一个包含要随每个请求发送的附加 HTTP 标头的对象。#
- forcedColors? <"active"|"none"> 模拟 'forced-colors' 媒体特性，支持的值为 'active'、'none'。有关详细信息，请参阅 page.emulateMedia([options])。默认为 'none'。#
- geolocation? <Object>#
  - latitude <number> -90 到 90 之间的纬度。
  - longitude <number> -180 到 180 之间的经度。
  - accuracy? <number> 非负精度值。默认为 0。
- hasTouch? <boolean> 指定视口是否支持触摸事件。默认为 false。#
- httpCredentials? <Object> HTTP 身份验证的凭据。#
  - username <string>
  - password <string>
- ignoreHTTPSErrors? <boolean> 发送网络请求时是否忽略 HTTPS 错误。默认为 false。#
- isMobile? <boolean> 是否考虑 meta viewport 标签并启用触摸事件。默认为 false。Firefox 不支持。#
- javaScriptEnabled? <boolean> 是否在上下文中启用 JavaScript。默认为 true。#
- locale? <string> 指定用户区域设置，例如 en-GB、de-DE 等。区域设置将影响 navigator.language 值、Accept-Language 请求标头值以及数字和日期格式规则。#
- logger? <Logger> Playwright 日志记录的记录器接收器。#
- offline? <boolean> 是否模拟网络离线。默认为 false。#
- permissions? <Array<string>> 要授予此上下文中所有页面的权限列表。有关详细信息，请参阅 browserContext.grantPermissions(permissions[, options])。#
- proxy? <Object> 要与此上下文一起使用的网络代理设置。#
  - server <string> 用于所有请求的代理。支持 HTTP 和 SOCKS 代理，例如 http://myproxy.com:3128 或 socks5://myproxy.com:3128。短格式 myproxy.com:3128 被视为 HTTP 代理。
  - bypass? <string> 可选的逗号分隔的域以绕过代理，例如 ".com, chromium.org, .domain.com"。
  - username? <string> 如果 HTTP 代理需要身份验证，则为可选用户名。
  - password? <string> 如果 HTTP 代理需要身份验证，则为可选密码。
  note
  对于 Windows 上的 Chromium，浏览器需要使用全局代理启动才能使此选项生效。如果所有上下文都覆盖代理，则永远不会使用全局代理，并且可以是任何字符串，例如 launch({ proxy: { server: 'http://per-context' } })。
- recordHar? <Object> 将所有页面的 HAR 录制启用进 recordHar.path 文件。如果未指定，则不录制 HAR。确保等待 browserContext.close() 以保存 HAR。#
  - omitContent? <boolean> 可选设置，用于控制是否从 HAR 中省略请求内容。默认为 false。已弃用，请改用 content 策略。
  - content? <"omit"|"embed"|"attach"> 可选设置，用于控制资源内容管理。如果指定 omit，则不持久化内容。如果指定 attach，则资源作为单独的文件或 ZIP 存档中的条目持久化。如果指定 embed，则根据 HAR 规范将内容内联存储在 HAR 文件中。对于 .zip 输出文件默认为 attach，对于所有其他文件扩展名默认为 embed。
  - path <string> 文件系统上写入 HAR 文件的路径。如果文件名以 .zip 结尾，则默认使用 content: 'attach'。
  - mode? <"full"|"minimal"> 当设置为 minimal 时，仅记录从 HAR 路由所需的信息。这将省略大小、时间、页面、cookie、安全性以及从 HAR 重播时不使用的其他类型的 HAR 信息。默认为 full。
  - urlFilter? <string|RegExp> 用于过滤存储在 HAR 中的请求的 glob 或 regex 模式。当通过上下文选项提供 baseURL 并且传递的 URL 是路径时，它会通过 new URL() 构造函数进行合并。
- recordVideo? <Object> 将所有页面的视频录制启用进 recordVideo.dir 目录。如果未指定，则不录制视频。确保等待 browserContext.close() 以保存视频。#
  - dir <string> 放入视频的目录路径。
  - size? <Object> 录制视频的可选尺寸。如果未指定，尺寸将等于缩放以适应 800x800 的 viewport。如果未显式配置 viewport，则视频尺寸默认为 800x450。如果需要，每个页面的实际图片将按比例缩小以适应指定尺寸。
    - width <number> 视频帧宽度。
    - height <number> 视频帧高度。
- reducedMotion? <"reduce"|"no-preference"> 模拟 'prefers-reduced-motion' 媒体特性，支持的值为 'reduce'、'no-preference'。有关详细信息，请参阅 page.emulateMedia([options])。默认为 'no-preference'。#
- screen? <Object> 模拟通过 window.screen 在网页内可用的如一窗口屏幕大小。仅在设置了 viewport 时使用。#
  - width <number> 页面宽度（以像素为单位）。
  - height <number> 页面高度（以像素为单位）。
- serviceWorkers? <"allow"|"block"> 是否允许站点注册 Service workers。默认为 'allow'。#
  - 'allow': 可以注册 Service Workers。
  - 'block': Playwright 将阻止所有 Service Workers 的注册。
- storageState? <string|Object> 使用给定的存储状态填充上下文。此选项可用于使用通过 browserContext.storageState([options]) 获取的登录信息初始化上下文。或者是保存存储的文件的路径，或者是具有以下字段的对象：#
  - cookies <Array<Object>> 要为上下文设置的 cookie
    - name <string>
    - value <string>
    - domain <string> 域和路径是必需的
    - path <string> 域和路径是必需的
    - expires <number> Unix 时间（以秒为单位）。
    - httpOnly <boolean>
    - secure <boolean>
    - sameSite <"Strict"|"Lax"|"None"> sameSite 标志
  - origins <Array<Object>> 要为上下文设置的 localStorage
    - origin <string>
    - localStorage <Array<Object>>
      - name <string>
      - value <string>
- strictSelectors? <boolean> 如果指定，则为此上下文启用严格选择器模式。在严格选择器模式下，所有暗示单个目标 DOM 元素的选择器操作在多个元素匹配选择器时都将抛出异常。请参阅 Locator 以了解有关严格模式的更多信息。#
- timezoneId? <string> 更改上下文的时区。有关支持的时区 ID 列表，请参阅 ICU 的 metaZones.txt。#
- userAgent? <string> 在此上下文中使用的特定用户代理。#
- videoSize? <Object> 已弃用 请改用 recordVideo。#
  - width <number> 视频帧宽度。
  - height <number> 视频帧高度。
- videosPath? <string> 已弃用 请改用 recordVideo。#
- viewport? <null|Object> 为每个页面模拟一致的视口。默认为 1280x720 视口。null 禁用默认视口。#
  - width <number> 页面宽度（以像素为单位）。
  - height <number> 页面高度（以像素为单位）。
returns: <Promise<BrowserContext>>#

创建一个新的浏览器上下文。它不会与其他浏览器上下文共享 cookie/缓存。

note

如果直接使用此方法创建 BrowserContext，最佳做法是在代码完成 BrowserContext 后，并在调用 browser.close() 之前，通过 browserContext.close() 显式关闭返回的上下文。这将确保 context 优雅关闭，并且任何工件（如 HAR 和视频）都完全刷新并保存。

(async () => {
  const browser = await playwright.firefox.launch();  // Or 'chromium' or 'webkit'.
  // Create a new incognito browser context.
  const context = await browser.newContext();
  // Create a new page in a pristine context.
  const page = await context.newPage();
  await page.goto('https://example.com');

  // Gracefully close up everything
  await context.close();
  await browser.close();
})();

browser.newPage([options])

Added in: v1.8

options? <Object>
- acceptDownloads? <boolean> 是否自动下载所有附件。默认为 true，接受所有下载。#
- baseURL? <string> 当使用 page.goto(url[, options])、page.route(url, handler[, options])、page.waitForURL(url[, options])、page.waitForRequest(urlOrPredicate[, options]) 或 page.waitForResponse(urlOrPredicate[, options]) 时，通过使用 URL() 构造函数构建相应的 URL 来考虑基本 URL。示例：#
  - baseURL: http://localhost:3000 并且导航到 /bar.html 结果为 http://localhost:3000/bar.html
  - baseURL: http://localhost:3000/foo/ 并且导航到 ./bar.html 结果为 http://localhost:3000/foo/bar.html
  - baseURL: http://localhost:3000/foo (没有尾随斜杠) 并且导航到 ./bar.html 结果为 http://localhost:3000/bar.html
- bypassCSP? <boolean> 切换绕过页面的 Content-Security-Policy。#
- colorScheme? <"light"|"dark"|"no-preference"> 模拟 'prefers-colors-scheme' 媒体特性，支持的值为 'light'、'dark'、'no-preference'。有关详细信息，请参阅 page.emulateMedia([options])。默认为 'light'。#
- deviceScaleFactor? <number> 指定设备缩放因子（可以认为是 dpr）。默认为 1。#
- extraHTTPHeaders? <Object<string, string>> 一个包含要随每个请求发送的附加 HTTP 标头的对象。#
- forcedColors? <"active"|"none"> 模拟 'forced-colors' 媒体特性，支持的值为 'active'、'none'。有关详细信息，请参阅 page.emulateMedia([options])。默认为 'none'。#
- geolocation? <Object>#
  - latitude <number> -90 到 90 之间的纬度。
  - longitude <number> -180 到 180 之间的经度。
  - accuracy? <number> 非负精度值。默认为 0。
- hasTouch? <boolean> 指定视口是否支持触摸事件。默认为 false。#
- httpCredentials? <Object> HTTP 身份验证的凭据。#
  - username <string>
  - password <string>
- ignoreHTTPSErrors? <boolean> 发送网络请求时是否忽略 HTTPS 错误。默认为 false。#
- isMobile? <boolean> 是否考虑 meta viewport 标签并启用触摸事件。默认为 false。Firefox 不支持。#
- javaScriptEnabled? <boolean> 是否在上下文中启用 JavaScript。默认为 true。#
- locale? <string> 指定用户区域设置，例如 en-GB、de-DE 等。区域设置将影响 navigator.language 值、Accept-Language 请求标头值以及数字和日期格式规则。#
- logger? <Logger> Playwright 日志记录的记录器接收器。#
- offline? <boolean> 是否模拟网络离线。默认为 false。#
- permissions? <Array<string>> 要授予此上下文中所有页面的权限列表。有关详细信息，请参阅 browserContext.grantPermissions(permissions[, options])。#
- proxy? <Object> 要与此上下文一起使用的网络代理设置。#
  - server <string> 用于所有请求的代理。支持 HTTP 和 SOCKS 代理，例如 http://myproxy.com:3128 或 socks5://myproxy.com:3128。短格式 myproxy.com:3128 被视为 HTTP 代理。
  - bypass? <string> 可选的逗号分隔的域以绕过代理，例如 ".com, chromium.org, .domain.com"。
  - username? <string> 如果 HTTP 代理需要身份验证，则为可选用户名。
  - password? <string> 如果 HTTP 代理需要身份验证，则为可选密码。
  note
  对于 Windows 上的 Chromium，浏览器需要使用全局代理启动才能使此选项生效。如果所有上下文都覆盖代理，则永远不会使用全局代理，并且可以是任何字符串，例如 launch({ proxy: { server: 'http://per-context' } })。
- recordHar? <Object> 将所有页面的 HAR 录制启用进 recordHar.path 文件。如果未指定，则不录制 HAR。确保等待 browserContext.close() 以保存 HAR。#
  - omitContent? <boolean> 可选设置，用于控制是否从 HAR 中省略请求内容。默认为 false。已弃用，请改用 content 策略。
  - content? <"omit"|"embed"|"attach"> 可选设置，用于控制资源内容管理。如果指定 omit，则不持久化内容。如果指定 attach，则资源作为单独的文件或 ZIP 存档中的条目持久化。如果指定 embed，则根据 HAR 规范将内容内联存储在 HAR 文件中。对于 .zip 输出文件默认为 attach，对于所有其他文件扩展名默认为 embed。
  - path <string> 文件系统上写入 HAR 文件的路径。如果文件名以 .zip 结尾，则默认使用 content: 'attach'。
  - mode? <"full"|"minimal"> 当设置为 minimal 时，仅记录从 HAR 路由所需的信息。这将省略大小、时间、页面、cookie、安全性以及从 HAR 重播时不使用的其他类型的 HAR 信息。默认为 full。
  - urlFilter? <string|RegExp> 用于过滤存储在 HAR 中的请求的 glob 或 regex 模式。当通过上下文选项提供 baseURL 并且传递的 URL 是路径时，它会通过 new URL() 构造函数进行合并。
- recordVideo? <Object> 将所有页面的视频录制启用进 recordVideo.dir 目录。如果未指定，则不录制视频。确保等待 browserContext.close() 以保存视频。#
  - dir <string> 放入视频的目录路径。
  - size? <Object> 录制视频的可选尺寸。如果未指定，尺寸将等于缩放以适应 800x800 的 viewport。如果未显式配置 viewport，则视频尺寸默认为 800x450。如果需要，每个页面的实际图片将按比例缩小以适应指定尺寸。
    - width <number> 视频帧宽度。
    - height <number> 视频帧高度。
- reducedMotion? <"reduce"|"no-preference"> 模拟 'prefers-reduced-motion' 媒体特性，支持的值为 'reduce'、'no-preference'。有关详细信息，请参阅 page.emulateMedia([options])。默认为 'no-preference'。#
- screen? <Object> 模拟通过 window.screen 在网页内可用的如一窗口屏幕大小。仅在设置了 viewport 时使用。#
  - width <number> 页面宽度（以像素为单位）。
  - height <number> 页面高度（以像素为单位）。
- serviceWorkers? <"allow"|"block"> 是否允许站点注册 Service workers。默认为 'allow'。#
  - 'allow': 可以注册 Service Workers。
  - 'block': Playwright 将阻止所有 Service Workers 的注册。
- storageState? <string|Object> 使用给定的存储状态填充上下文。此选项可用于使用通过 browserContext.storageState([options]) 获取的登录信息初始化上下文。或者是保存存储的文件的路径，或者是具有以下字段的对象：#
  - cookies <Array<Object>> 要为上下文设置的 cookie
    - name <string>
    - value <string>
    - domain <string> 域和路径是必需的
    - path <string> 域和路径是必需的
    - expires <number> Unix 时间（以秒为单位）。
    - httpOnly <boolean>
    - secure <boolean>
    - sameSite <"Strict"|"Lax"|"None"> sameSite 标志
  - origins <Array<Object>> 要为上下文设置的 localStorage
    - origin <string>
    - localStorage <Array<Object>>
      - name <string>
      - value <string>
- strictSelectors? <boolean> 如果指定，则为此上下文启用严格选择器模式。在严格选择器模式下，所有暗示单个目标 DOM 元素的选择器操作在多个元素匹配选择器时都将抛出异常。请参阅 Locator 以了解有关严格模式的更多信息。#
- timezoneId? <string> 更改上下文的时区。有关支持的时区 ID 列表，请参阅 ICU 的 metaZones.txt。#
- userAgent? <string> 在此上下文中使用的特定用户代理。#
- videoSize? <Object> 已弃用 请改用 recordVideo。#
  - width <number> 视频帧宽度。
  - height <number> 视频帧高度。
- videosPath? <string> 已弃用 请改用 recordVideo。#
- viewport? <null|Object> 为每个页面模拟一致的视口。默认为 1280x720 视口。null 禁用默认视口。#
  - width <number> 页面宽度（以像素为单位）。
  - height <number> 页面高度（以像素为单位）。
returns: <Promise<Page>>#

在新的浏览器上下文中创建一个新页面。关闭此页面也将关闭上下文。

这是一个方便的 API，应仅用于单页场景和简短的代码片段。生产代码和测试框架应显式创建 browser.newContext([options])，然后调用 browserContext.newPage() 以控制其确切的生命周期。

browser.startTracing([page, options])

Added in: v1.11

page? <Page> 可选，如果指定，跟踪将包含给定页面的屏幕截图。#
options? <Object>
- categories? <Array<string>> 指定要使用的自定义类别而不是默认类别。#
- path? <string> 写入跟踪文件的路径。#
- screenshots? <boolean> 在跟踪中捕获屏幕截图。#
returns: <Promise<void>>#

note

此 API 控制 Chromium Tracing，这是一个低级 chromium 特定调试工具。控制 Playwright Tracing 的 API 可以在这里找到。

您可以使用 browser.startTracing([page, options]) 和 browser.stopTracing() 创建一个可以在 Chrome DevTools 性能面板中打开的跟踪文件。

await browser.startTracing(page, {path: 'trace.json'});
await page.goto('https://www.google.com');
await browser.stopTracing();

browser.stopTracing()

Added in: v1.11

returns: <Promise<Buffer>>#

note

此 API 控制 Chromium Tracing，这是一个低级 chromium 特定调试工具。控制 Playwright Tracing 的 API 可以在这里找到。

返回带有跟踪数据的缓冲区。

browser.version()

Added in: v1.8

returns: <string>#

返回浏览器版本。

browser.on('disconnected')​

browser.browserType()​

browser.close()​

browser.contexts()​

browser.isConnected()​

browser.newBrowserCDPSession()​

browser.newContext([options])​

browser.newPage([options])​

browser.startTracing([page, options])​

browser.stopTracing()​

browser.version()​

browser.on('disconnected')

browser.browserType()

browser.close()

browser.contexts()

browser.isConnected()

browser.newBrowserCDPSession()

browser.newContext([options])

browser.newPage([options])

browser.startTracing([page, options])

browser.stopTracing()

browser.version()