Browser

浏览器是通过 browserType.launch() 创建的。使用 Browser 创建 Page 的示例：

🌐 A Browser is created via browserType.launch(). An example of using a Browser to create a 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();
})();

方法

🌐 Methods

browserType

Added in: v1.23

browser.browserType

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

🌐 Get the browser type (chromium, firefox or webkit) that the browser belongs to.

用法

browser.browserType();

BrowserType #

close

Added before v1.9

browser.close

如果这个浏览器是通过 browserType.launch() 获取的，会关闭浏览器及其所有页面（如果有打开的话）。

🌐 In case this browser is obtained using browserType.launch(), closes the browser and all of its pages (if any were opened).

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

🌐 In case this browser is connected to, clears all created contexts belonging to this browser and disconnects from the browser server.

note

这类似于强制退出浏览器。要优雅地关闭页面并确保你收到页面关闭事件，请在调用 browser.close() 之前，对你之前使用 browser.newContext() 明确创建的任何 BrowserContext 实例调用 browserContext.close() 。

🌐 This is similar to force-quitting the browser. To close pages gracefully and ensure you receive page close events, call browserContext.close() on any BrowserContext instances you explicitly created earlier using browser.newContext() before calling browser.close().

【Browser】对象本身已被认为是已释放状态，不能再使用。

🌐 The Browser object itself is considered to be disposed and cannot be used anymore.

用法

await browser.close();
await browser.close(options);

参数

options Object (optional)
- reason string (optional) Added in: v1.40#
  
  报告的原因是由于浏览器关闭而中断的操作。

Promise<void>#

contexts

Added before v1.9

browser.contexts

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

🌐 Returns an array of all open browser contexts. In a newly created browser, this will return zero browser contexts.

用法

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`

Array<BrowserContext>#

isConnected

Added before v1.9

browser.isConnected

表示浏览器已连接。

🌐 Indicates that the browser is connected.

用法

browser.isConnected();

boolean #

newBrowserCDPSession

Added in: v1.11

browser.newBrowserCDPSession

note

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

🌐 CDP Sessions are only supported on Chromium-based browsers.

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

🌐 Returns the newly created browser session.

用法

await browser.newBrowserCDPSession();

Promise<CDPSession>#

newContext

Added before v1.9

browser.newContext

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

🌐 Creates a new browser context. It won't share cookies/cache with other browser contexts.

note

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

🌐 If directly using this method to create BrowserContexts, it is best practice to explicitly close the returned context via browserContext.close() when your code is done with the BrowserContext, and before calling browser.close(). This will ensure the context is closed gracefully and any artifacts—like HARs and videos—are fully flushed and saved.

用法

(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();
})();

参数

options Object (optional)
- acceptDownloads boolean (optional)#
  
  是否自动下载所有附件。默认值为 true，表示接受所有下载。
- baseURL string (optional)#
  
  在使用 page.goto()、page.route()、page.waitForURL()、page.waitForRequest() 或 page.waitForResponse() 时，会通过使用 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 (optional)#
  
  切换是否绕过页面的内容安全策略。默认值为 false。
- clientCertificates Array<Object> (optional) Added in: 1.46#
  - origin string
    
    证书有效的确切来源。来源包括 https 协议、主机名以及可选的端口。
  - certPath string (optional)
    
    PEM 格式的证书文件路径。
  - cert Buffer (optional)
    
    PEM 格式的证书的直接值。
  - keyPath string (optional)
    
    PEM 格式的私钥文件路径。
  - key Buffer (optional)
    
    PEM 格式的私钥的直接值。
  - pfxPath string (optional)
    
    PFX 或 PKCS12 编码的私钥和证书链的路径。
  - pfx Buffer (optional)
    
    PFX 或 PKCS12 编码的私钥和证书链的直接值。
  - passphrase string (optional)
    
    私钥的密码（PEM 或 PFX）。
  TLS 客户端身份验证允许服务器请求客户端证书并对其进行验证。
  
  详情
  
  要使用的一组客户端证书。每个证书对象必须同时具有 certPath 和 keyPath，或者单独具有 pfxPath，或它们对应的直接值等效项（cert 和 key，或 pfx）。如果证书是加密的，则可选择提供 passphrase 属性。origin 属性应提供与证书有效的请求来源完全匹配的值。
  
  客户端证书认证仅在提供至少一个客户端证书时才有效。如果你想拒绝服务器发送的所有客户端证书，你需要提供一个 origin 与你计划访问的任何域名都不匹配的客户端证书。
  
  note
  在 macOS 上使用 WebKit 时，访问 localhost 不会使用客户端证书。你可以通过将 localhost 替换为 local.playwright 来使其正常工作。
- colorScheme null | "light" | "dark" | "no-preference" (optional)#
  
  模拟 prefers-colors-scheme 媒体特性，支持的值为 'light' 和 'dark'。更多详情请参见 page.emulateMedia()。传入 null 可将模拟重置为系统默认值。默认值为 'light'。
- contrast null | "no-preference" | "more" (optional)#
  
  模拟 'prefers-contrast' 媒体特性，支持的值为 'no-preference'、'more'。更多详情请参见 page.emulateMedia()。传递 null 会将模拟重置为系统默认值。默认为 'no-preference'。
- deviceScaleFactor number (optional)#
  
  指定设备缩放因子（可以理解为 DPR）。默认值为 1。了解有关使用设备缩放因子模拟设备的更多信息。
- extraHTTPHeaders Object<string, string> (optional)#
  
  一个包含附加 HTTP 头的对象，这些头将随每个请求发送。默认为无。
- forcedColors null | "active" | "none" (optional)#
  
  模拟 'forced-colors' 媒体特性，支持的值为 'active'、'none'。更多详情请参见 page.emulateMedia()。传递 null 会将模拟重置为系统默认值。默认为 'none'。
- geolocation Object (optional)#
  - latitude number
    
    纬度在 -90 到 90 之间。
  - longitude number
    
    经度在 -180 到 180 之间。
  - accuracy number (optional)
    
    非负精度值。默认值为 0。
- hasTouch boolean (optional)#
  
  指定视口是否支持触摸事件。默认值为 false。了解更多关于移动模拟的信息。
- httpCredentials Object (optional)#
  - username string
  - password string
  - origin string (optional)
    
    限制在特定来源 (scheme://host:port) 上发送 http 凭据。
  - send "unauthorized" | "always" (optional)
    
    此选项仅适用于从对应的 APIRequestContext 发送的请求，并不影响从浏览器发送的请求。'always' - Authorization 头信息会随每个 API 请求发送基本认证凭据。'unauthorized - 凭据仅在收到带有 WWW-Authenticate 头的 401（未授权）响应时发送。默认为 'unauthorized'。
  HTTP 认证的凭据。如果未指定来源，用户名和密码将在收到未授权响应时发送到任何服务器。
- ignoreHTTPSErrors boolean (optional)#
  
  发送网络请求时是否忽略 HTTPS 错误。默认值为 false。
- isMobile boolean (optional)#
  
  是否考虑 meta viewport 标签并启用触摸事件。isMobile 是 device 的一部分，因此你实际上不需要手动设置它。默认值为 false，并且在 Firefox 中不受支持。了解更多关于移动端模拟的信息。
- javaScriptEnabled boolean (optional)#
  
  是否在此环境中启用 JavaScript。默认为 true。了解更多关于禁用 JavaScript的信息。
- locale string (optional)#
  
  指定用户区域设置，例如 en-GB、de-DE 等。区域设置会影响 navigator.language 的值、Accept-Language 请求头的值以及数字和日期的格式规则。默认为系统默认区域设置。有关模拟的更多信息，请参阅我们的模拟指南。
- logger Logger (optional)#
  
  已弃用
  日志记录器接收到的日志不完整。请改用追踪。
  
  用于 Playwright 日志记录的日志器接收器。
- offline boolean (optional)#
  
  是否模拟网络离线。默认为 false。了解更多关于网络模拟的信息。
- permissions Array<string> (optional)#
  
  在此上下文中授予所有页面的权限列表。有关更多详细信息，请参阅 browserContext.grantPermissions()。默认情况下无权限。
- proxy Object (optional)#
  - server string
    
    用于所有请求的代理。支持 HTTP 和 SOCKS 代理，例如 http://myproxy.com:3128 或 socks5://myproxy.com:3128。简写 myproxy.com:3128 被视为 HTTP 代理。
  - bypass string (optional)
    
    可选的以逗号分隔的域名，用于绕过代理，例如 ".com, chromium.org, .domain.com"。
  - username string (optional)
    
    如果 HTTP 代理需要身份验证，则使用可选的用户名。
  - password string (optional)
    
    如果 HTTP 代理需要身份验证，则使用可选密码。
  在此上下文中使用的网络代理设置。默认情况下为无。
- recordHar Object (optional)#
  - omitContent boolean (optional)
    
    可选设置，用于控制是否从 HAR 中省略请求内容。默认值为 false。已弃用，请改用 content 策略。
  - content "omit" | "embed" | "attach" (optional)
    
    可选设置，用于控制资源内容管理。如果指定 omit，内容不会被保存。如果指定 attach，资源将作为单独的文件或 ZIP 压缩包中的条目保存。如果指定 embed，内容将根据 HAR 规范内联存储在 HAR 文件中。默认情况下，对于 .zip 输出文件为 attach，对于所有其他文件扩展名为 embed。
  - path string
    
    要写入 HAR 文件的文件系统路径。如果文件名以 .zip 结尾，则默认使用 content: 'attach'。
  - mode "full" | "minimal" (optional)
    
    当设置为 minimal 时，仅记录从 HAR 路由所需的信息。这会省略在从 HAR 回放时不使用的大小、时间、页面、Cookies、安全性以及其他类型的 HAR 信息。默认值为 full。
  - urlFilter string | RegExp (optional)
    
    用于过滤存储在 HAR 中的请求的全局或正则表达式模式。当通过上下文选项提供了 baseURL 并且传入的 URL 是路径时，它会通过 new URL() 构造函数进行合并。默认情况下没有。
  启用对所有页面的 HAR 记录，并保存到 recordHar.path 文件中。如果未指定，则不会记录 HAR。请确保在保存 HAR 前等待 browserContext.close()。
- recordVideo Object (optional)#
  - dir string
    
    放置视频的目录路径。
  - size Object (optional)
    - width number
      
      视频帧宽度。
    - height number
      
      视频帧高度。
    录制视频的可选尺寸。如果未指定，大小将等于 viewport 并缩小以适应 800x800。如果未显式配置 viewport，视频大小默认为 800x450。每页的实际画面如有必要将缩小以适应指定尺寸。
  启用将所有页面的视频录制到 recordVideo.dir 目录。如果未指定，则不会录制视频。请确保等待 browserContext.close() 以便保存视频。
- reducedMotion null | "reduce" | "no-preference" (optional)#
  
  模拟 'prefers-reduced-motion' 媒体特性，支持的值为 'reduce'、'no-preference'。更多详情请参见 page.emulateMedia()。传递 null 会将模拟重置为系统默认值。默认为 'no-preference'。
- screen Object (optional)#
  - width number
    
    页面宽度（以像素为单位）。
  - height number
    
    页面高度（以像素为单位）。
  通过 window.screen 模拟网页内可用的一致窗口屏幕大小。仅在设置了 viewport 时使用。
- serviceWorkers "allow" | "block" (optional)#
  
  是否允许网站注册服务工作进程。默认值为 'allow'。
  - 'allow'：服务工作者可以被注册。
  - 'block'：Playwright 将阻止所有服务工作进程的注册。
- storageState string | Object (optional)#
  - cookies Array<Object>
    - name string
    - value string
    - domain string
      
      域和路径是必填项。若要使 cookie 适用于所有子域，请在域名前加一个点，如：.example.com
    - path string
      
      域名和路径为必填项
    - expires number
      
      Unix 时间以秒为单位。
    - httpOnly boolean
    - secure boolean
    - sameSite “严格” | “宽松” | “无”
      
      同一站点标志
    为上下文设置的 Cookie
  - origins Array<Object>
    - origin string
    - localStorage Array<Object>
      - name string
      - value string
      localStorage 设置上下文
  了解更多关于存储状态和身份验证的信息。
  
  使用给定的存储状态填充上下文。此选项可用于使用通过 browserContext.storageState() 获取的登录信息初始化上下文。
- strictSelectors boolean (optional)#
  
  如果设置为 true，则为此上下文启用严格选择器模式。在严格选择器模式下，对选择器进行的所有操作，如果操作意图是单个目标 DOM 元素，当有多个元素匹配选择器时将会抛出错误。此选项不会影响任何定位器（Locator）API（定位器始终是严格的）。默认值为 false。请参阅 Locator 了解有关严格模式的更多信息。
- timezoneId string (optional)#
  
  更改上下文的时区。有关支持的时区 ID 列表，请参阅 ICU 的 metaZones.txt。默认使用系统时区。
- userAgent string (optional)#
  
  在此上下文中使用的特定用户代理。
- videoSize Object (optional)#
  
  ：：：警告[已弃用] 请使用[recordVideo]（/api/class-browser.mdx#browser-new-context-option-record-video）。 :::
  - width number
    
    视频帧宽度。
  - height number
    
    视频帧高度。
- videosPath string (optional)#
  
  ：：：警告[已弃用] 请使用[recordVideo]（/api/class-browser.mdx#browser-new-context-option-record-video）。 :::
- viewport null | Object (optional)#
  - width number
    
    页面宽度（以像素为单位）。
  - height number
    
    页面高度（以像素为单位）。
  为每个页面模拟一致的视口。默认视口为 1280x720。使用 null 可禁用一致视口模拟。了解更多关于视口模拟的信息。
  
  note
  null 值选择不使用默认预设，使视口依赖于操作系统定义的主机窗口大小。这会导致测试执行结果不确定。

Promise<BrowserContext>#

newPage

Added before v1.9

browser.newPage

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

🌐 Creates a new page in a new browser context. Closing this page will close the context as well.

这是一个便捷的 API，只应在单页场景和简短片段中使用。生产代码和测试框架应显式地创建 browser.newContext()，然后再创建 browserContext.newPage()，以便精确控制它们的生命周期。

🌐 This is a convenience API that should only be used for the single-page scenarios and short snippets. Production code and testing frameworks should explicitly create browser.newContext() followed by the browserContext.newPage() to control their exact life times.

用法

await browser.newPage();
await browser.newPage(options);

参数

options Object (optional)
- acceptDownloads boolean (optional)#
  
  是否自动下载所有附件。默认值为 true，表示接受所有下载。
- baseURL string (optional)#
  
  在使用 page.goto()、page.route()、page.waitForURL()、page.waitForRequest() 或 page.waitForResponse() 时，会通过使用 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 (optional)#
  
  切换是否绕过页面的内容安全策略。默认值为 false。
- clientCertificates Array<Object> (optional) Added in: 1.46#
  - origin string
    
    证书有效的确切来源。来源包括 https 协议、主机名以及可选的端口。
  - certPath string (optional)
    
    PEM 格式的证书文件路径。
  - cert Buffer (optional)
    
    PEM 格式的证书的直接值。
  - keyPath string (optional)
    
    PEM 格式的私钥文件路径。
  - key Buffer (optional)
    
    PEM 格式的私钥的直接值。
  - pfxPath string (optional)
    
    PFX 或 PKCS12 编码的私钥和证书链的路径。
  - pfx Buffer (optional)
    
    PFX 或 PKCS12 编码的私钥和证书链的直接值。
  - passphrase string (optional)
    
    私钥的密码（PEM 或 PFX）。
  TLS 客户端身份验证允许服务器请求客户端证书并对其进行验证。
  
  详情
  
  要使用的一组客户端证书。每个证书对象必须同时具有 certPath 和 keyPath，或者单独具有 pfxPath，或它们对应的直接值等效项（cert 和 key，或 pfx）。如果证书是加密的，则可选择提供 passphrase 属性。origin 属性应提供与证书有效的请求来源完全匹配的值。
  
  客户端证书认证仅在提供至少一个客户端证书时才有效。如果你想拒绝服务器发送的所有客户端证书，你需要提供一个 origin 与你计划访问的任何域名都不匹配的客户端证书。
  
  note
  在 macOS 上使用 WebKit 时，访问 localhost 不会使用客户端证书。你可以通过将 localhost 替换为 local.playwright 来使其正常工作。
- colorScheme null | "light" | "dark" | "no-preference" (optional)#
  
  模拟 prefers-colors-scheme 媒体特性，支持的值为 'light' 和 'dark'。更多详情请参见 page.emulateMedia()。传入 null 可将模拟重置为系统默认值。默认值为 'light'。
- contrast null | "no-preference" | "more" (optional)#
  
  模拟 'prefers-contrast' 媒体特性，支持的值为 'no-preference'、'more'。更多详情请参见 page.emulateMedia()。传递 null 会将模拟重置为系统默认值。默认为 'no-preference'。
- deviceScaleFactor number (optional)#
  
  指定设备缩放因子（可以理解为 DPR）。默认值为 1。了解有关使用设备缩放因子模拟设备的更多信息。
- extraHTTPHeaders Object<string, string> (optional)#
  
  一个包含附加 HTTP 头的对象，这些头将随每个请求发送。默认为无。
- forcedColors null | "active" | "none" (optional)#
  
  模拟 'forced-colors' 媒体特性，支持的值为 'active'、'none'。更多详情请参见 page.emulateMedia()。传递 null 会将模拟重置为系统默认值。默认为 'none'。
- geolocation Object (optional)#
  - latitude number
    
    纬度在 -90 到 90 之间。
  - longitude number
    
    经度在 -180 到 180 之间。
  - accuracy number (optional)
    
    非负精度值。默认值为 0。
- hasTouch boolean (optional)#
  
  指定视口是否支持触摸事件。默认值为 false。了解更多关于移动模拟的信息。
- httpCredentials Object (optional)#
  - username string
  - password string
  - origin string (optional)
    
    限制在特定来源 (scheme://host:port) 上发送 http 凭据。
  - send "unauthorized" | "always" (optional)
    
    此选项仅适用于从对应的 APIRequestContext 发送的请求，并不影响从浏览器发送的请求。'always' - Authorization 头信息会随每个 API 请求发送基本认证凭据。'unauthorized - 凭据仅在收到带有 WWW-Authenticate 头的 401（未授权）响应时发送。默认为 'unauthorized'。
  HTTP 认证的凭据。如果未指定来源，用户名和密码将在收到未授权响应时发送到任何服务器。
- ignoreHTTPSErrors boolean (optional)#
  
  发送网络请求时是否忽略 HTTPS 错误。默认值为 false。
- isMobile boolean (optional)#
  
  是否考虑 meta viewport 标签并启用触摸事件。isMobile 是 device 的一部分，因此你实际上不需要手动设置它。默认值为 false，并且在 Firefox 中不受支持。了解更多关于移动端模拟的信息。
- javaScriptEnabled boolean (optional)#
  
  是否在此环境中启用 JavaScript。默认为 true。了解更多关于禁用 JavaScript的信息。
- locale string (optional)#
  
  指定用户区域设置，例如 en-GB、de-DE 等。区域设置会影响 navigator.language 的值、Accept-Language 请求头的值以及数字和日期的格式规则。默认为系统默认区域设置。有关模拟的更多信息，请参阅我们的模拟指南。
- logger Logger (optional)#
  
  已弃用
  日志记录器接收到的日志不完整。请改用追踪。
  
  用于 Playwright 日志记录的日志器接收器。
- offline boolean (optional)#
  
  是否模拟网络离线。默认为 false。了解更多关于网络模拟的信息。
- permissions Array<string> (optional)#
  
  在此上下文中授予所有页面的权限列表。有关更多详细信息，请参阅 browserContext.grantPermissions()。默认情况下无权限。
- proxy Object (optional)#
  - server string
    
    用于所有请求的代理。支持 HTTP 和 SOCKS 代理，例如 http://myproxy.com:3128 或 socks5://myproxy.com:3128。简写 myproxy.com:3128 被视为 HTTP 代理。
  - bypass string (optional)
    
    可选的以逗号分隔的域名，用于绕过代理，例如 ".com, chromium.org, .domain.com"。
  - username string (optional)
    
    如果 HTTP 代理需要身份验证，则使用可选的用户名。
  - password string (optional)
    
    如果 HTTP 代理需要身份验证，则使用可选密码。
  在此上下文中使用的网络代理设置。默认情况下为无。
- recordHar Object (optional)#
  - omitContent boolean (optional)
    
    可选设置，用于控制是否从 HAR 中省略请求内容。默认值为 false。已弃用，请改用 content 策略。
  - content "omit" | "embed" | "attach" (optional)
    
    可选设置，用于控制资源内容管理。如果指定 omit，内容不会被保存。如果指定 attach，资源将作为单独的文件或 ZIP 压缩包中的条目保存。如果指定 embed，内容将根据 HAR 规范内联存储在 HAR 文件中。默认情况下，对于 .zip 输出文件为 attach，对于所有其他文件扩展名为 embed。
  - path string
    
    要写入 HAR 文件的文件系统路径。如果文件名以 .zip 结尾，则默认使用 content: 'attach'。
  - mode "full" | "minimal" (optional)
    
    当设置为 minimal 时，仅记录从 HAR 路由所需的信息。这会省略在从 HAR 回放时不使用的大小、时间、页面、Cookies、安全性以及其他类型的 HAR 信息。默认值为 full。
  - urlFilter string | RegExp (optional)
    
    用于过滤存储在 HAR 中的请求的全局或正则表达式模式。当通过上下文选项提供了 baseURL 并且传入的 URL 是路径时，它会通过 new URL() 构造函数进行合并。默认情况下没有。
  启用对所有页面的 HAR 记录，并保存到 recordHar.path 文件中。如果未指定，则不会记录 HAR。请确保在保存 HAR 前等待 browserContext.close()。
- recordVideo Object (optional)#
  - dir string
    
    放置视频的目录路径。
  - size Object (optional)
    - width number
      
      视频帧宽度。
    - height number
      
      视频帧高度。
    录制视频的可选尺寸。如果未指定，大小将等于 viewport 并缩小以适应 800x800。如果未显式配置 viewport，视频大小默认为 800x450。每页的实际画面如有必要将缩小以适应指定尺寸。
  启用将所有页面的视频录制到 recordVideo.dir 目录。如果未指定，则不会录制视频。请确保等待 browserContext.close() 以便保存视频。
- reducedMotion null | "reduce" | "no-preference" (optional)#
  
  模拟 'prefers-reduced-motion' 媒体特性，支持的值为 'reduce'、'no-preference'。更多详情请参见 page.emulateMedia()。传递 null 会将模拟重置为系统默认值。默认为 'no-preference'。
- screen Object (optional)#
  - width number
    
    页面宽度（以像素为单位）。
  - height number
    
    页面高度（以像素为单位）。
  通过 window.screen 模拟网页内可用的固定窗口屏幕大小。仅在设置了 viewport 时使用。
- serviceWorkers "allow" | "block" (optional)#
  
  是否允许网站注册服务工作进程。默认值为 'allow'。
  - 'allow'：服务工作者可以被注册。
  - 'block'：Playwright 将阻止所有服务工作进程的注册。
- storageState string | Object (optional)#
  - cookies Array<Object>
    - name string
    - value string
    - domain string
      
      域和路径是必填项。若要使 cookie 适用于所有子域，请在域名前加一个点，如：.example.com
    - path string
      
      域名和路径为必填项
    - expires number
      
      Unix 时间以秒为单位。
    - httpOnly boolean
    - secure boolean
    - sameSite “严格” | “宽松” | “无”
      
      同一站点标志
    为上下文设置的 Cookie
  - origins Array<Object>
    - origin string
    - localStorage Array<Object>
      - name string
      - value string
      localStorage 设置上下文
  了解更多关于存储状态和身份验证的信息。
  
  使用给定的存储状态填充上下文。此选项可用于使用通过 browserContext.storageState() 获取的登录信息初始化上下文。
- strictSelectors boolean (optional)#
  
  如果设置为 true，则为此上下文启用严格选择器模式。在严格选择器模式下，对选择器进行的所有操作，如果操作意图是单个目标 DOM 元素，当有多个元素匹配选择器时将会抛出错误。此选项不会影响任何定位器（Locator）API（定位器始终是严格的）。默认值为 false。请参阅 Locator 了解有关严格模式的更多信息。
- timezoneId string (optional)#
  
  更改上下文的时区。有关支持的时区 ID 列表，请参阅 ICU 的 metaZones.txt。默认使用系统时区。
- userAgent string (optional)#
  
  在此上下文中使用的特定用户代理。
- videoSize Object (optional)#
  
  已弃用
  请改用 recordVideo。
  - width number
    
    视频帧宽度。
  - height number
    
    视频帧高度。
- videosPath string (optional)#
  
  已弃用
  请改用 recordVideo。
- viewport null | Object (optional)#
  - width number
    
    页面宽度（以像素为单位）。
  - height number
    
    页面高度（以像素为单位）。
  为每个页面模拟一致的视口。默认视口为 1280x720。使用 null 可禁用一致视口模拟。了解更多关于视口模拟的信息。
  
  note
  null 值选择不使用默认预设，使视口依赖于操作系统定义的主机窗口大小。这会导致测试执行结果不确定。

Promise<Page>#

removeAllListeners

Added in: v1.47

browser.removeAllListeners

移除指定类型的所有监听器（如果未指定类型，则移除所有注册的监听器）。允许等待异步监听器完成，或忽略这些监听器随后产生的错误。

🌐 Removes all the listeners of the given type (or all registered listeners if no type given). Allows to wait for async listeners to complete or to ignore subsequent errors from these listeners.

用法

await browser.removeAllListeners();
await browser.removeAllListeners(type, options);

参数

type string (optional)#
options Object (optional)
- behavior "wait" | "ignoreErrors" | "default" (optional)#
  
  指定是否等待已经运行的监听器以及如果它们抛出错误该怎么做： =
  - 'default' - 不要等待当前监听器的调用（如果有）完成，如果监听器抛出异常，可能会导致未处理的错误
  - 'wait' - 等待当前监听器调用（如果有）完成
  - 'ignoreErrors' - 不要等待当前监听器的调用（如果有的话）完成，移除后监听器抛出的所有错误都会被静默捕获

Promise<void>#

startTracing

Added in: v1.11

browser.startTracing

note

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

🌐 This API controls Chromium Tracing which is a low-level chromium-specific debugging tool. API to control Playwright Tracing could be found here.

你可以使用 browser.startTracing() 和 browser.stopTracing() 来创建一个可在 Chrome 开发者工具性能面板中打开的跟踪文件。

🌐 You can use browser.startTracing() and browser.stopTracing() to create a trace file that can be opened in Chrome DevTools performance panel.

用法

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

参数

page Page (optional)#

可选（如果指定），跟踪包括给定页面的屏幕截图。
options Object (optional)
- categories Array<string> (optional)#
  
  指定要使用的自定义类别而不是默认类别。
- path string (optional)#
  
  写入跟踪文件的路径。
- screenshots boolean (optional)#
  
  捕获跟踪中的屏幕截图。

Promise<void>#

stopTracing

Added in: v1.11

browser.stopTracing

note

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

🌐 This API controls Chromium Tracing which is a low-level chromium-specific debugging tool. API to control Playwright Tracing could be found here.

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

🌐 Returns the buffer with trace data.

用法

await browser.stopTracing();

Promise<Buffer>#

version

Added before v1.9

browser.version

返回浏览器版本。

🌐 Returns the browser version.

用法

browser.version();

string #

事件

🌐 Events

on('disconnected')

Added before v1.9

browser.on('disconnected')

当浏览器与浏览器应用断开连接时触发。这可能由以下原因之一导致：

🌐 Emitted when Browser gets disconnected from the browser application. This might happen because of one of the following:

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

用法

browser.on('disconnected', data => {});

事件数据

Browser

方法​

browserType​

close​

contexts​

isConnected​

newBrowserCDPSession​

newContext​

newPage​

removeAllListeners​

startTracing​

stopTracing​

version​

事件​

on('disconnected')​

方法

browserType

close

contexts

isConnected

newBrowserCDPSession

newContext

newPage

removeAllListeners

startTracing

stopTracing

version

事件

on('disconnected')