Playwright中Browser的实现类深度解析-Browser方法速查手册

这是一个Java接口Browser，它继承自AutoCloseable，用于表示一个浏览器实例。该接口提供了创建浏览器上下文、页面、追踪等功能。以下是对其属性和方法的详细解析：

属性

Browser接口本身没有定义属性，但是其内部定义了三个静态内部类CloseOptions、NewContextOptions、NewPageOptions、StartTracingOptions，它们各自有一些属性，具体如下：

1. CloseOptions类属性：
   • reason：
     • 作用：用于设置浏览器关闭时，报告给被浏览器关闭所中断的操作的原因。
     • 默认值：无
     • 使用场景：当需要明确告知相关操作浏览器关闭的原因时使用，例如在日志记录或者错误处理中需要详细的关闭原因信息。
2. NewContextOptions类属性：
   • acceptDownloads：
     • 作用：决定是否自动下载所有附件。
     • 默认值：true，即默认接受所有下载。
     • 使用场景：在自动化测试或者模拟浏览器行为时，如果需要自动处理下载操作，可使用此属性。若不希望自动下载，可设置为false。
   • baseURL：
     • 作用：在使用Page的navigate、route、waitForURL、waitForRequest、waitForResponse等方法时，作为构建相应URL的基础URL。
     • 默认值：未设置。
     • 使用场景：当需要在相对路径的基础上快速构建完整URL时，可设置此属性。例如，在测试某个网站的多个页面时，若这些页面的URL都基于同一个基础URL，设置baseURL可以简化URL的编写。
   • bypassCSP：
     • 作用：用于切换是否绕过页面的内容安全策略（CSP）。
     • 默认值：false，即默认不绕过CSP。
     • 使用场景：在测试或者开发过程中，如果需要访问一些被CSP限制的资源，可设置为true来绕过CSP进行测试或调试。
   • clientCertificates：
     • 作用：用于TLS客户端认证，包含客户端证书信息，使服务器能够验证客户端证书。
     • 默认值：无
     • 使用场景：当访问需要客户端证书认证的网站时，设置此属性提供相应的证书信息。
   • colorScheme：
     • 作用：模拟prefers-color-scheme媒体特性，支持的值为"light"和"dark"。
     • 默认值：Optional.of(ColorScheme.LIGHT)，即默认模拟亮色主题。
     • 使用场景：在测试不同颜色主题下网站的显示效果时，可通过设置此属性模拟用户的颜色偏好。
   • contrast：
     • 作用：模拟"prefers-contrast"媒体特性，支持的值为"no-preference"、"more"。
     • 默认值：Optional.of(Contrast.NO_PREFERENCE)，即默认无对比度偏好。
     • 使用场景：在测试网站在不同对比度偏好下的显示效果时使用。
   • deviceScaleFactor：
     • 作用：指定设备缩放因子（可视为dpr）。
     • 默认值：1
     • 使用场景：在模拟不同设备屏幕像素密度时使用，例如测试高分辨率屏幕下网站的显示效果。
   • extraHTTPHeaders：
     • 作用：包含要随每个请求发送的额外HTTP头信息。
     • 默认值：无
     • 使用场景：当需要在请求中添加自定义的HTTP头时使用，例如添加认证信息、自定义标识等。
   • forcedColors：
     • 作用：模拟"forced-colors"媒体特性，支持的值为"active"、"none"。
     • 默认值：Optional.of(ForcedColors.NONE)，即默认无强制颜色。
     • 使用场景：在测试网站在强制颜色模式下的显示效果时使用。
   • geolocation：
     • 作用：设置地理位置信息。
     • 默认值：无
     • 使用场景：在测试需要获取用户地理位置的功能时，设置模拟的地理位置。
   • hasTouch：
     • 作用：指定视口是否支持触摸事件。
     • 默认值：false
     • 使用场景：在模拟移动设备或者触摸屏幕设备时，设置此属性开启触摸事件支持。
   • httpCredentials：
     • 作用：提供HTTP认证的凭据。
     • 默认值：无
     • 使用场景：当访问需要HTTP认证的网站时，设置用户名和密码等认证信息。
   • ignoreHTTPSErrors：
     • 作用：决定在发送网络请求时是否忽略HTTPS错误。
     • 默认值：false，即默认不忽略HTTPS错误。
     • 使用场景：在测试或者开发过程中，如果需要访问自签名证书或者存在HTTPS配置问题的网站时，可设置为true忽略错误继续访问。
   • isMobile：
     • 作用：决定是否将meta viewport标签考虑在内并启用触摸事件，且该属性是设备的一部分，一般无需手动设置。
     • 默认值：false，且在Firefox中不支持。
     • 使用场景：在模拟移动设备访问网站时使用，可使浏览器模拟移动设备的一些特性。
   • javaScriptEnabled：
     • 作用：决定是否在上下文中启用JavaScript。
     • 默认值：true，即默认启用JavaScript。
     • 使用场景：在测试网站在禁用JavaScript情况下的功能时，可设置为false。
   • locale：
     • 作用：指定用户区域设置，例如"en-GB"、"de-DE"等，会影响navigator.language值、Accept-Language请求头值以及数字和日期格式化规则。
     • 默认值：系统默认区域设置。
     • 使用场景：在测试网站在不同语言和区域设置下的显示和功能时使用。
   • offline：
     • 作用：决定是否模拟网络离线状态。
     • 默认值：false，即默认不模拟离线。
     • 使用场景：在测试网站在离线状态下的功能，如离线缓存、离线提示等功能时使用。
   • permissions：
     • 作用：指定要授予此上下文中所有页面的权限列表。
     • 默认值：无
     • 使用场景：在测试需要特定权限的功能时，如访问摄像头、麦克风等权限，可设置此属性授予相应权限。
   • proxy：
     • 作用：设置此上下文使用的网络代理设置。
     • 默认值：无
     • 使用场景：当需要通过代理服务器访问网络时，设置代理相关信息。
   • recordHarContent：
     • 作用：用于控制资源内容管理，若设置为omit，则不持久化内容；若设置为attach，资源将作为单独文件持久化并与HAR文件一起存档；默认值embed，则按照HAR规范将内容内联存储在HAR文件中。
     • 默认值：HarContentPolicy.EMBED
     • 使用场景：在记录HTTP存档（HAR）时，根据需求选择不同的内容存储方式。
   • recordHarMode：
     • 作用：当设置为minimal时，仅记录HAR中路由所需的信息，省略大小、时间、页面、cookie、安全等在从HAR重放时不使用的信息；默认值为full，记录完整信息。
     • 默认值：HarMode.FULL
     • 使用场景：在对HAR文件大小有要求或者只关注关键路由信息时，可设置为minimal。
   • recordHarOmitContent：
     • 作用：控制是否从HAR中省略请求内容。
     • 默认值：false，即默认不省略请求内容。
     • 使用场景：在对HAR文件大小敏感且不需要请求内容时，可设置为true。
   • recordHarPath：
     • 作用：启用对所有页面的HAR记录，并将记录保存到指定的文件系统路径下的HAR文件中。
     • 默认值：无
     • 使用场景：在需要记录HTTP请求和响应信息以便分析时，设置此属性指定保存路径。
   • recordHarUrlFilter：
     • 作用：过滤HAR记录的URL。
     • 默认值：无
     • 使用场景：当只需要记录特定URL的请求和响应信息时，设置此属性进行过滤。
   • recordVideoDir：
     • 作用：启用对所有页面的视频录制，并将视频保存到指定目录。
     • 默认值：无
     • 使用场景：在需要录制浏览器操作视频进行调试或者演示时，设置此属性指定保存目录。
   • recordVideoSize：
     • 作用：指定录制视频的尺寸。若未指定，大小将等于viewport缩小到适合800x800的尺寸；若viewport未显式配置，视频大小默认为800x450。
     • 默认值：未指定时根据viewport或默认尺寸800x450
     • 使用场景：在对录制视频的尺寸有特定要求时，设置此属性。
   • reducedMotion：
     • 作用：模拟"prefers-reduced-motion"媒体特性，支持的值为"reduce"、"no-preference"。
     • 默认值：Optional.of(ReducedMotion.NO_PREFERENCE)，即默认无减少运动偏好。
     • 使用场景：在测试网站在减少运动偏好设置下的显示效果时使用。
   • screenSize：
     • 作用：模拟通过window.screen在网页内可用的一致窗口屏幕大小，仅在设置了viewport时使用。
     • 默认值：无
     • 使用场景：在测试网站在不同屏幕尺寸下的显示效果时使用。
   • serviceWorkers：
     • 作用：决定是否允许站点注册Service Workers，"allow"表示允许注册，"block"表示阻止所有Service Workers的注册。
     • 默认值：ServiceWorkerPolicy.ALLOW，即默认允许注册。
     • 使用场景：在测试Service Workers相关功能时，根据需求设置是否允许注册。
   • storageState：
     • 作用：使用给定的存储状态填充上下文，可用于通过BrowserContext.storageState()获取的登录信息初始化上下文。
     • 默认值：无
     • 使用场景：在需要复用之前保存的登录状态等存储信息时使用。
   • storageStatePath：
     • 作用：指定保存存储状态的文件路径，同样用于使用给定的存储状态填充上下文。
     • 默认值：无
     • 使用场景：与storageState类似，只是通过文件路径来获取存储状态信息。
   • strictSelectors：
     • 作用：如果设置为true，则为该上下文启用严格选择器模式。在严格选择器模式下，对暗示单个目标DOM元素的选择器的所有操作，当有多个元素匹配选择器时将抛出异常。此选项不影响任何定位器API（定位器始终是严格的）。
     • 默认值：false
     • 使用场景：在对选择器的准确性要求较高，不允许模糊匹配时，设置此属性启用严格模式。
   • timezoneId：
     • 作用：更改上下文的时区，可参考ICU的metaZones.txt获取支持的时区ID列表。
     • 默认值：系统时区。
     • 使用场景：在测试网站在不同时区下的时间显示、定时任务等功能时使用。
   • userAgent：
     • 作用：指定在此上下文中使用的特定用户代理。
     • 默认值：无
     • 使用场景：在需要模拟特定浏览器或者设备的用户代理时使用。
   • viewportSize：
     • 作用：模拟每个页面的一致视口，默认值为1280x720的视口，使用null可禁用一致视口模拟。
     • 默认值：Optional.of(new ViewportSize(1280, 720))
     • 使用场景：在测试网站在不同视口尺寸下的显示效果时使用，若希望视口根据操作系统窗口大小变化，可设置为null。
3. NewPageOptions类属性：与NewContextOptions类属性基本相同，具体如下：
   • acceptDownloads - baseURL - bypassCSP - clientCertificates - colorScheme - contrast - deviceScaleFactor - extraHTTPHeaders - forcedColors - geolocation - hasTouch - httpCredentials - ignoreHTTPSErrors - isMobile - javaScriptEnabled - locale - offline - permissions - proxy - recordHarContent - recordHarMode - recordHarOmitContent - recordHarPath - recordHarUrlFilter - recordVideoDir - recordVideoSize - reducedMotion - screenSize - serviceWorkers - storageState - storageStatePath - strictSelectors - timezoneId - userAgent - viewportSize：
     • 作用：同NewContextOptions中对应属性。
     • 默认值：同NewContextOptions中对应属性。
     • 使用场景：同NewContextOptions中对应属性，主要用于创建新页面时设置页面相关的各种选项。
4. StartTracingOptions类属性：
   • categories：
     • 作用：指定要使用的自定义类别，而不是默认类别。
     • 默认值：无
     • 使用场景：在进行Chromium追踪时，如果需要自定义追踪的类别，可设置此属性。
   • path：
     • 作用：指定写入追踪文件的路径。
     • 默认值：无
     • 使用场景：在需要保存追踪文件时，设置此属性指定保存路径。
   • screenshots：
     • 作用：决定是否在追踪中捕获屏幕截图。
     • 默认值：无
     • 使用场景：在追踪过程中，如果希望记录屏幕截图以便更直观地分析操作过程，可设置为true。

方法

1. onDisconnected(Consumer<Browser> handler)：
   • 入参解析：
     • handler：一个Consumer<Browser>类型的处理器，无默认值，用于处理浏览器断开连接的事件。
   • 出参解析：无返回值。
   • 方法签名：void onDisconnected(Consumer<Browser> handler)
   • 核心作用：为浏览器添加一个断开连接的事件处理器，当浏览器与浏览器应用程序断开连接时，会触发该处理器。
   • 使用场景：在需要对浏览器断开连接的情况进行处理时，例如记录日志、进行资源清理等操作时使用。
2. offDisconnected(Consumer<Browser> handler)：
   • 入参解析：
     • handler：一个Consumer<Browser>类型的处理器，无默认值，用于移除之前通过onDisconnected方法添加的事件处理器。
   • 出参解析：无返回值。
   • 方法签名：void offDisconnected(Consumer<Browser> handler)
   • 核心作用：移除之前添加的浏览器断开连接事件处理器。
   • 使用场景：当不再需要处理浏览器断开连接事件时，可调用此方法移除对应的处理器。
3. browserType()：
   • 入参解析：无参数。
   • 出参解析：返回一个BrowserType对象，用于表示浏览器所属的类型（chromium、firefox或webkit）。
   • 方法签名：BrowserType browserType()
   • 核心作用：获取浏览器所属的类型。
   • 使用场景：在需要根据浏览器类型进行不同操作时，例如针对不同浏览器类型设置不同的测试策略。
4. close()：
   • 入参解析：无参数。
   • 出参解析：无返回值。
   • 方法签名：default void close()