BrowserType

BrowserType 提供了启动特定浏览器实例或连接到现有浏览器实例的方法。以下是使用 Playwright 驱动自动化的典型示例

import com.microsoft.playwright.*;

public class Example {
  public static void main(String[] args) {
    try (Playwright playwright = Playwright.create()) {
      BrowserType chromium = playwright.chromium();
      Browser browser = chromium.launch();
      Page page = browser.newPage();
      page.navigate("https://example.com");
      // other actions...
      browser.close();
    }
  }
}

方法

connect

在 v1.9 之前添加

browserType.connect

此方法将 Playwright 附加到现有的浏览器实例。当连接到另一个通过 Node.js 中的 BrowserType.launchServer 启动的浏览器时，主版本号和次版本号需要与客户端版本匹配 (1.2.3 → 与 1.2.x 兼容)。

用法

BrowserType.connect(wsEndpoint);
BrowserType.connect(wsEndpoint, options);

参数

wsEndpoint StringAdded in: v1.10#

要连接到的浏览器 websocket 端点。
options BrowserType.ConnectOptions (可选)
- setExposeNetwork String (可选)Added in: v1.37#
  
  此选项将连接客户端上可用的网络公开给要连接的浏览器。由逗号分隔的规则列表组成。
  
  可用规则
  1. 主机名模式，例如：example.com、*.org:99、x.*.y.com、*foo.org。
  2. IP 字面量，例如：127.0.0.1、0.0.0.0:99、[::1]、[0:0::1]:99。
  3. <loopback> 匹配本地环回接口：localhost、*.localhost、127.0.0.1、[::1]。
  一些常见示例
  1. "*" 以公开所有网络。
  2. "<loopback>" 以公开 localhost 网络。
  3. "*.test.internal-domain,*.staging.internal-domain,<loopback>" 以公开测试/预发布部署和 localhost。
- setHeaders Map<String, String> (可选)Added in: v1.11#
  
  要随 web socket 连接请求一起发送的其他 HTTP 标头。可选。
- setSlowMo double (可选)Added in: v1.10#
  
  以指定的毫秒数减慢 Playwright 操作的速度。有助于您查看正在发生的事情。默认为 0。
- setTimeout double (可选)Added in: v1.10#
  
  等待建立连接的最长时间（以毫秒为单位）。默认为 0 (无超时)。

返回值

Browser #

connectOverCDP

Added in: v1.9

browserType.connectOverCDP

此方法使用 Chrome DevTools 协议将 Playwright 附加到现有的浏览器实例。

默认浏览器上下文可通过 Browser.contexts() 访问。

注意

通过 Chrome DevTools 协议连接仅支持基于 Chromium 的浏览器。

用法

Browser browser = playwright.chromium().connectOverCDP("https://127.0.0.1:9222");
BrowserContext defaultContext = browser.contexts().get(0);
Page page = defaultContext.pages().get(0);

参数

endpointURL StringAdded in: v1.11#

要连接到的 CDP websocket 端点或 http url。例如 https://127.0.0.1:9222/ 或 ws://127.0.0.1:9222/devtools/browser/387adf4c-243f-4051-a181-46798f4a46f4。
options BrowserType.ConnectOverCDPOptions (可选)
- setHeaders Map<String, String> (可选)Added in: v1.11#
  
  要随连接请求一起发送的其他 HTTP 标头。可选。
- setSlowMo double (可选)Added in: v1.11#
  
  以指定的毫秒数减慢 Playwright 操作的速度。有助于您查看正在发生的事情。默认为 0。
- setTimeout double (可选)Added in: v1.11#
  
  等待建立连接的最长时间（以毫秒为单位）。默认为 30000 (30 秒)。传递 0 以禁用超时。

返回值

Browser #

executablePath

在 v1.9 之前添加

browserType.executablePath

Playwright 期望找到捆绑浏览器可执行文件的路径。

用法

BrowserType.executablePath();

返回值

String #

launch

在 v1.9 之前添加

browserType.launch

返回浏览器实例。

用法

您可以使用 setIgnoreDefaultArgs 从默认参数中过滤掉 --mute-audio

// Or "firefox" or "webkit".
Browser browser = chromium.launch(new BrowserType.LaunchOptions()
  .setIgnoreDefaultArgs(Arrays.asList("--mute-audio")));

仅限 Chromium Playwright 也可用于控制 Google Chrome 或 Microsoft Edge 浏览器，但它与捆绑的 Chromium 版本配合使用效果最佳。不保证它适用于任何其他版本。请极其谨慎地使用 setExecutablePath 选项。

如果首选 Google Chrome（而不是 Chromium），建议使用 Chrome Canary 或 Dev Channel 版本。

Stock browsers like Google Chrome and Microsoft Edge are suitable for tests that require proprietary media codecs for video playback. See this article for other differences between Chromium and Chrome. This article describes some differences for Linux users.

参数

options BrowserType.LaunchOptions (可选)
- setArgs List<String> (可选)#
  
  警告
  使用自定义浏览器参数的风险自负，因为其中一些参数可能会破坏 Playwright 功能。
  
  要传递给浏览器实例的其他参数。Chromium 标志列表可以在此处找到。
- setChannel String (可选)#
  
  浏览器分发渠道。
  
  使用 "chromium" 选择加入新的无头模式。
  
  使用 "chrome"、"chrome-beta"、"chrome-dev"、"chrome-canary"、"msedge"、"msedge-beta"、"msedge-dev" 或 "msedge-canary" 以使用品牌 Google Chrome 和 Microsoft Edge。
- setChromiumSandbox boolean (可选)#
  
  启用 Chromium 沙盒。默认为 false。
- setDevtools boolean (可选)#
  
  已弃用
  请改用调试工具。
  
  仅限 Chromium 是否为每个选项卡自动打开开发者工具面板。如果此选项为 true，则 setHeadless 选项将设置为 false。
- setDownloadsPath Path (可选)#
  
  如果指定，接受的下载将下载到此目录中。否则，将创建临时目录，并在浏览器关闭时删除。在任何情况下，下载都会在创建它们的浏览器上下文关闭时删除。
- setEnv Map<String, String> (可选)#
  
  指定浏览器可见的环境变量。默认为 process.env。
- setExecutablePath Path (可选)#
  
  要运行的浏览器可执行文件的路径，而不是捆绑的可执行文件。如果 setExecutablePath 是相对路径，则它相对于当前工作目录解析。请注意，Playwright 仅适用于捆绑的 Chromium、Firefox 或 WebKit，风险自负。
- setFirefoxUserPrefs Map<String, Object> (可选)#
  
  Firefox 用户首选项。在 about:config 了解更多关于 Firefox 用户首选项的信息。
- setHandleSIGHUP boolean (可选)#
  
  在 SIGHUP 上关闭浏览器进程。默认为 true。
- setHandleSIGINT boolean (可选)#
  
  在 Ctrl-C 上关闭浏览器进程。默认为 true。
- setHandleSIGTERM boolean (可选)#
  
  在 SIGTERM 上关闭浏览器进程。默认为 true。
- setHeadless boolean (可选)#
  
  是否在无头模式下运行浏览器。有关 Chromium 和 Firefox 的更多详细信息。默认为 true，除非 setDevtools 选项为 true。
- setIgnoreAllDefaultArgs boolean (可选)Added in: v1.9#
  
  如果为 true，Playwright 不传递自己的配置参数，而仅使用来自 setArgs 的参数。危险选项；谨慎使用。默认为 false。
- setIgnoreDefaultArgs List<String> (可选)#
  
  如果为 true，Playwright 不传递自己的配置参数，而仅使用来自 setArgs 的参数。危险选项；谨慎使用。
- setProxy Proxy (可选)#
  - setServer String
    
    用于所有请求的代理。支持 HTTP 和 SOCKS 代理，例如 http://myproxy.com:3128 或 socks5://myproxy.com:3128。简短形式 myproxy.com:3128 被视为 HTTP 代理。
  - setBypass String (可选)
    
    可选的逗号分隔的域以绕过代理，例如 ".com, chromium.org, .domain.com"。
  - setUsername String (可选)
    
    如果 HTTP 代理需要身份验证，则使用的可选用户名。
  - setPassword String (可选)
    
    如果 HTTP 代理需要身份验证，则使用的可选密码。
  网络代理设置。
- setSlowMo double (可选)#
  
  以指定的毫秒数减慢 Playwright 操作的速度。有助于您查看正在发生的事情。
- setTimeout double (可选)#
  
  等待浏览器实例启动的最长时间（以毫秒为单位）。默认为 30000 (30 秒)。传递 0 以禁用超时。
- setTracesDir Path (可选)#
  
  如果指定，跟踪将保存到此目录中。

返回值

Browser #

launchPersistentContext

在 v1.9 之前添加

browserType.launchPersistentContext

返回持久浏览器上下文实例。

启动使用位于 userDataDir 的持久存储的浏览器，并返回唯一的上下文。关闭此上下文将自动关闭浏览器。

用法

BrowserType.launchPersistentContext(userDataDir);
BrowserType.launchPersistentContext(userDataDir, options);

参数

userDataDir Path #

用户数据目录的路径，用于存储浏览器会话数据，如 Cookie 和本地存储。有关 Chromium 和 Firefox 的更多详细信息。请注意，Chromium 的用户数据目录是 chrome://version 中看到的“Profile Path”的父目录。传递空字符串以使用临时目录。
options BrowserType.LaunchPersistentContextOptions (可选)
- setAcceptDownloads boolean (可选)#
  
  是否自动下载所有附件。默认为 true，其中接受所有下载。
- setArgs List<String> (可选)#
  
  警告
  使用自定义浏览器参数的风险自负，因为其中一些参数可能会破坏 Playwright 功能。
  
  要传递给浏览器实例的其他参数。Chromium 标志列表可以在此处找到。
- setBaseURL String (可选)#
  
  当使用 Page.navigate()、Page.route()、Page.waitForURL()、Page.waitForRequest() 或 Page.waitForResponse() 时，它会通过使用 URL() 构造函数来构建相应的 URL，从而考虑基本 URL。默认情况下未设置。示例
  - baseURL: https://127.0.0.1:3000 and navigating to /bar.html results in https://127.0.0.1:3000/bar.html
  - baseURL: https://127.0.0.1:3000/foo/ and navigating to ./bar.html results in https://127.0.0.1:3000/foo/bar.html
  - baseURL: https://127.0.0.1:3000/foo (without trailing slash) and navigating to ./bar.html results in https://127.0.0.1:3000/bar.html
- setBypassCSP boolean (可选)#
  
  切换绕过页面的内容安全策略 (Content-Security-Policy)。默认为 false。
- setChannel String (可选)#
  
  浏览器分发渠道。
  
  使用 "chromium" 选择加入新的无头模式。
  
  使用 "chrome"、"chrome-beta"、"chrome-dev"、"chrome-canary"、"msedge"、"msedge-beta"、"msedge-dev" 或 "msedge-canary" 以使用品牌 Google Chrome 和 Microsoft Edge。
- setChromiumSandbox boolean (可选)#
  
  启用 Chromium 沙盒。默认为 false。
- setClientCertificates List<ClientCertificates> (可选)Added in: 1.46#
  - setOrigin String
    
    证书有效的确切来源。来源包括 https 协议、主机名和可选端口。
  - setCertPath Path (可选)
    
    PEM 格式的证书文件路径。
  - setCert byte[] (可选)
    
    PEM 格式的证书直接值。
  - setKeyPath Path (可选)
    
    PEM 格式的私钥文件路径。
  - setKey byte[] (可选)
    
    PEM 格式的私钥直接值。
  - setPfxPath Path (可选)
    
    PFX 或 PKCS12 编码的私钥和证书链的路径。
  - setPfx byte[] (可选)
    
    PFX 或 PKCS12 编码的私钥和证书链的直接值。
  - setPassphrase String (可选)
    
    私钥（PEM 或 PFX）的密码。
  TLS 客户端身份验证允许服务器请求客户端证书并验证它。
  
  详情
  
  要使用的客户端证书数组。每个证书对象必须同时具有 certPath 和 keyPath、单个 pfxPath 或其相应的直接值等效项（cert 和 key，或 pfx）。可选地，如果证书已加密，则应提供 passphrase 属性。origin 属性应与证书有效的请求来源完全匹配。
  
  注意
  在 macOS 上使用 WebKit 时，访问 localhost 不会获取客户端证书。您可以通过将 localhost 替换为 local.playwright 使其工作。
- setColorScheme null | enum ColorScheme { LIGHT, DARK, NO_PREFERENCE } (可选)#
  
  模拟 prefers-colors-scheme 媒体功能，支持的值为 'light' 和 'dark'。有关更多详细信息，请参阅 Page.emulateMedia()。传递 null 会将模拟重置为系统默认值。默认为 'light'。
- setDeviceScaleFactor double (可选)#
  
  指定设备比例因子（可以认为是 dpr）。默认为 1。了解有关使用设备比例因子模拟设备的更多信息。
- setDevtools boolean (可选)#
  
  已弃用
  请改用调试工具。
  
  仅限 Chromium 是否为每个选项卡自动打开开发者工具面板。如果此选项为 true，则 setHeadless 选项将设置为 false。
- setDownloadsPath Path (可选)#
  
  如果指定，接受的下载将下载到此目录中。否则，将创建临时目录，并在浏览器关闭时删除。在任何情况下，下载都会在创建它们的浏览器上下文关闭时删除。
- setEnv Map<String, String> (可选)#
  
  指定浏览器可见的环境变量。默认为 process.env。
- setExecutablePath Path (可选)#
  
  要运行的浏览器可执行文件的路径，而不是捆绑的可执行文件。如果 setExecutablePath 是相对路径，则它相对于当前工作目录解析。请注意，Playwright 仅适用于捆绑的 Chromium、Firefox 或 WebKit，风险自负。
- setExtraHTTPHeaders Map<String, String> (可选)#
  
  一个包含要随每个请求一起发送的额外 HTTP 标头的对象。默认为无。
- setFirefoxUserPrefs Map<String, Object> (可选)添加于: v1.40#
  
  Firefox 用户首选项。在 about:config 了解更多关于 Firefox 用户首选项的信息。
- setForcedColors null | enum ForcedColors { ACTIVE, NONE } (可选)#
  
  模拟 'forced-colors' 媒体功能，支持的值为 'active', 'none'。有关更多详细信息，请参阅 Page.emulateMedia()。传递 null 会将模拟重置为系统默认值。默认为 'none'。
- setGeolocation Geolocation (可选)#
  - setLatitude double
    
    纬度，介于 -90 和 90 之间。
  - setLongitude double
    
    经度，介于 -180 和 180 之间。
  - setAccuracy double (可选)
    
    非负精度值。默认为 0。
- setHandleSIGHUP boolean (可选)#
  
  在 SIGHUP 上关闭浏览器进程。默认为 true。
- setHandleSIGINT boolean (可选)#
  
  在 Ctrl-C 上关闭浏览器进程。默认为 true。
- setHandleSIGTERM boolean (可选)#
  
  在 SIGTERM 上关闭浏览器进程。默认为 true。
- setHasTouch boolean (可选)#
  
  指定视口是否支持触摸事件。默认为 false。了解有关移动设备模拟的更多信息。
- setHeadless boolean (可选)#
  
  是否在无头模式下运行浏览器。有关 Chromium 和 Firefox 的更多详细信息。默认为 true，除非 setDevtools 选项为 true。
- setHttpCredentials HttpCredentials (可选)#
  - setUsername String
  - setPassword String
  - setOrigin String (可选)
    
    限制在特定来源上发送 http 凭据 (scheme://host:port).
  - setSend enum HttpCredentialsSend { UNAUTHORIZED, ALWAYS } (可选)
    
    此选项仅适用于从相应的 APIRequestContext 发送的请求，并且不影响从浏览器发送的请求。 'always' - 具有基本身份验证凭据的 Authorization 标头将随每个 API 请求一起发送。 'unauthorized' - 凭据仅在收到带有 WWW-Authenticate 标头的 401（未授权）响应时发送。默认为 'unauthorized'。
  用于 HTTP 身份验证的凭据。如果未指定来源，则用户名和密码将在收到未授权响应时发送到任何服务器。
- setIgnoreAllDefaultArgs boolean (可选)Added in: v1.9#
  
  如果为 true，Playwright 不会传递其自己的配置参数，而仅使用来自 setArgs 的参数。危险选项；谨慎使用。默认为 false。
- setIgnoreDefaultArgs List<String> (可选)#
  
  如果为 true，Playwright 不会传递其自己的配置参数，而仅使用来自 setArgs 的参数。危险选项；谨慎使用。
- setIgnoreHTTPSErrors boolean (可选)#
  
  是否在发送网络请求时忽略 HTTPS 错误。默认为 false。
- setIsMobile boolean (可选)#
  
  是否考虑 meta viewport 标记并启用触摸事件。isMobile 是设备的一部分，因此实际上不需要手动设置它。默认为 false，并且在 Firefox 中不受支持。了解有关移动设备模拟的更多信息。
- setJavaScriptEnabled boolean (可选)#
  
  是否在此上下文中启用 JavaScript。默认为 true。了解有关禁用 JavaScript的更多信息。
- setLocale String (可选)#
  
  指定用户区域设置，例如 en-GB、de-DE 等。区域设置将影响 navigator.language 值、Accept-Language 请求标头值以及数字和日期格式规则。默认为系统默认区域设置。在我们的模拟指南中了解有关模拟的更多信息。
- setOffline boolean (可选)#
  
  是否模拟网络离线。默认为 false。了解有关网络模拟的更多信息。
- setPermissions List<String> (可选)#
  
  要授予此上下文中所有页面的权限列表。有关更多详细信息，请参阅 BrowserContext.grantPermissions()。默认为无。
- setProxy Proxy (可选)#
  - setServer String
    
    用于所有请求的代理。支持 HTTP 和 SOCKS 代理，例如 http://myproxy.com:3128 或 socks5://myproxy.com:3128。简短形式 myproxy.com:3128 被视为 HTTP 代理。
  - setBypass String (可选)
    
    可选的逗号分隔的域以绕过代理，例如 ".com, chromium.org, .domain.com"。
  - setUsername String (可选)
    
    如果 HTTP 代理需要身份验证，则使用的可选用户名。
  - setPassword String (可选)
    
    如果 HTTP 代理需要身份验证，则使用的可选密码。
  网络代理设置。
- setRecordHarContent enum HarContentPolicy { OMIT, EMBED, ATTACH } (可选)#
  
  用于控制资源内容管理的可选设置。如果指定 omit，则不会持久保存内容。如果指定 attach，则资源将作为单独的文件持久保存，并且所有这些文件将与 HAR 文件一起存档。默认为 embed，它按照 HAR 规范将内容内联存储在 HAR 文件中。
- setRecordHarMode enum HarMode { FULL, MINIMAL } (可选)#
  
  当设置为 minimal 时，仅记录从 HAR 路由所需的信息。这省略了大小、计时、页面、cookie、安全性和其他类型的 HAR 信息，这些信息在从 HAR 重放时未使用。默认为 full。
- setRecordHarOmitContent boolean (可选)#
  
  用于控制是否从 HAR 中省略请求内容的可选设置。默认为 false。
- setRecordHarPath Path (可选)#
  
  为所有页面启用 HAR 记录，并将记录到文件系统上指定的 HAR 文件中。如果未指定，则不记录 HAR。请确保调用 BrowserContext.close() 以保存 HAR。
- setRecordHarUrlFilter String | Pattern (可选)#
- setRecordVideoDir Path (可选)#
  
  为所有页面启用视频录制，并将录制到指定目录中。如果未指定，则不录制视频。请确保调用 BrowserContext.close() 以保存视频。
- setRecordVideoSize RecordVideoSize (可选)#
  - setWidth int
    
    视频帧宽度。
  - setHeight int
    
    视频帧高度。
  录制视频的尺寸。如果未指定，则尺寸将等于 viewport，并缩小以适合 800x800。如果未显式配置 viewport，则视频尺寸默认为 800x450。如果需要，每个页面的实际图片将被缩小以适合指定的尺寸。
- setReducedMotion null | enum ReducedMotion { REDUCE, NO_PREFERENCE } (可选)#
  
  模拟 'prefers-reduced-motion' 媒体功能，支持的值为 'reduce', 'no-preference'。有关更多详细信息，请参阅 Page.emulateMedia()。传递 null 会将模拟重置为系统默认值。默认为 'no-preference'。
- setScreenSize ScreenSize (可选)#
  - setWidth int
    
    页面宽度（像素）。
  - setHeight int
    
    页面高度（像素）。
  模拟通过 window.screen 在网页内部可访问的一致窗口屏幕尺寸。仅当设置了 setViewportSize 时才使用。
- setServiceWorkers enum ServiceWorkerPolicy { ALLOW, BLOCK } (可选)#
  
  是否允许站点注册 Service Worker。默认为 'allow'。
  - 'allow': 可以注册 Service Worker。
  - 'block': Playwright 将阻止所有 Service Worker 的注册。
- setSlowMo double (可选)#
  
  以指定的毫秒数减慢 Playwright 操作的速度。有助于您查看正在发生的事情。
- setStrictSelectors boolean (可选)#
  
  如果设置为 true，则为此上下文启用严格选择器模式。在严格选择器模式下，当多个元素与选择器匹配时，对暗示单个目标 DOM 元素的选择器的所有操作都将抛出异常。此选项不影响任何 Locator API（Locator 始终是严格的）。默认为 false。请参阅 Locator 以了解有关严格模式的更多信息。
- setTimeout double (可选)#
  
  等待浏览器实例启动的最长时间（以毫秒为单位）。默认为 30000 (30 秒)。传递 0 以禁用超时。
- setTimezoneId String (可选)#
  
  更改上下文的时区。有关支持的时区 ID 列表，请参阅 ICU's metaZones.txt。默认为系统时区。
- setTracesDir Path (可选)#
  
  如果指定，跟踪将保存到此目录中。
- setUserAgent String (可选)#
  
  在此上下文中使用的特定用户代理。
- setViewportSize null | ViewportSize (可选)#
  - setWidth int
    
    页面宽度（像素）。
  - setHeight int
    
    页面高度（像素）。
  为每个页面模拟一致的视口。默认为 1280x720 视口。使用 null 禁用一致的视口模拟。了解有关视口模拟的更多信息。
  
  注意
  null 值选择退出默认预设，使视口取决于操作系统定义的主机窗口大小。这使得测试的执行具有不确定性。

返回值

BrowserContext #

name

在 v1.9 之前添加

browserType.name

返回浏览器名称。例如：'chromium'、'webkit' 或 'firefox'。

用法

BrowserType.name();

返回值

String #

方法​

connect​

connectOverCDP​

executablePath​

launch​

launchPersistentContext​

name​

方法

connect

connectOverCDP

executablePath

launch

launchPersistentContext

name