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 String新增於：v1.10#

要連接的瀏覽器 websocket 端點。
options BrowserType.ConnectOptions (選用)
- setExposeNetwork String (選用)新增於：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> (選用)新增於：v1.11#
  
  要與 web socket 連接請求一起傳送的其他 HTTP 標頭。選用。
- setSlowMo double (選用)新增於：v1.10#
  
  將 Playwright 操作速度減慢指定的毫秒數。方便您查看正在發生的事情。預設為 0。
- setTimeout double (選用)新增於：v1.10#
  
  等待建立連線的最長時間（以毫秒為單位）。預設為 0（無逾時）。

回傳

Browser #

connectOverCDP

新增於：v1.9

browserType.connectOverCDP

此方法使用 Chrome DevTools Protocol 將 Playwright 連接到現有的瀏覽器實例。

預設瀏覽器內容可透過 Browser.contexts() 存取。

注意

透過 Chrome DevTools Protocol 連接僅支援 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 String新增於：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> (選用)新增於：v1.11#
  
  要與連線請求一起傳送的其他 HTTP 標頭。選用。
- setSlowMo double (選用)新增於：v1.11#
  
  將 Playwright 操作速度減慢指定的毫秒數。方便您查看正在發生的事情。預設為 0。
- setTimeout double (選用)新增於：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 版本。

Google Chrome 和 Microsoft Edge 等庫存瀏覽器適用於需要專有媒體編解碼器進行視訊播放的測試。請參閱這篇文章，瞭解 Chromium 和 Chrome 之間的其他差異。這篇文章描述了 Linux 使用者的一些差異。

參數

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 (選用)新增於：v1.9#
  
  如果為 true，Playwright 不會傳遞其自身的組態引數，而僅使用來自 setArgs 的引數。危險選項；謹慎使用。預設為 false。
- setIgnoreDefaultArgs List<String> (選用)#
  
  如果為 true，Playwright 不會傳遞其自身的組態引數，而僅使用來自 setArgs 的引數。危險選項；謹慎使用。
- setProxy Proxy (選用)#
  - setServer String
    
    用於所有請求的 Proxy。支援 HTTP 和 SOCKS Proxy，例如 http://myproxy.com:3128 或 socks5://myproxy.com:3128。簡短形式 myproxy.com:3128 被視為 HTTP Proxy。
  - setBypass String (選用)
    
    要繞過 Proxy 的選用逗號分隔網域，例如 ".com, chromium.org, .domain.com"。
  - setUsername String (選用)
    
    如果 HTTP Proxy 需要驗證，則為要使用的選用使用者名稱。
  - setPassword String (選用)
    
    如果 HTTP Proxy 需要驗證，則為要使用的選用密碼。
  網路 Proxy 設定。
- 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 中看到的「設定檔路徑」的父目錄。傳遞空字串以改為使用暫存目錄。
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 且導覽至 /bar.html 會產生 https://127.0.0.1:3000/bar.html
  - baseURL：https://127.0.0.1:3000/foo/ 且導覽至 ./bar.html 會產生 https://127.0.0.1:3000/foo/bar.html
  - baseURL：https://127.0.0.1:3000/foo（沒有尾部斜線）且導覽至 ./bar.html 會產生 https://127.0.0.1:3000/bar.html
- setBypassCSP boolean (選用)#
  
  切換繞過頁面的內容安全策略。預設為 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> (選用)新增於：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 （選填）
    
    限制在特定來源 (scheme://host:port).
  - setSend enum HttpCredentialsSend { UNAUTHORIZED, ALWAYS } （選填）
    
    此選項僅適用於從對應的 APIRequestContext 發送的請求，不影響從瀏覽器發送的請求。'always' - 每次 API 請求都會發送帶有基本身份驗證憑證的 Authorization 標頭。'unauthorized - 僅當收到帶有 WWW-Authenticate 標頭的 401 (Unauthorized) 回應時，才會發送憑證。預設值為 'unauthorized'。
  用於 HTTP 身份驗證的憑證。如果未指定來源，則使用者名稱和密碼會在收到未經授權的回應時發送到任何伺服器。
- setIgnoreAllDefaultArgs boolean (選用)新增於：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
    
    用於所有請求的 Proxy。支援 HTTP 和 SOCKS Proxy，例如 http://myproxy.com:3128 或 socks5://myproxy.com:3128。簡短形式 myproxy.com:3128 被視為 HTTP Proxy。
  - setBypass String (選用)
    
    要繞過 Proxy 的選用逗號分隔網域，例如 ".com, chromium.org, .domain.com"。
  - setUsername String (選用)
    
    如果 HTTP Proxy 需要驗證，則為要使用的選用使用者名稱。
  - setPassword String (選用)
    
    如果 HTTP Proxy 需要驗證，則為要使用的選用密碼。
  網路 Proxy 設定。
- setRecordHarContent enum HarContentPolicy { OMIT, EMBED, ATTACH } （選填）#
  
  用於控制資源內容管理的選填設定。如果指定 omit，則不會持久保存內容。如果指定 attach，則資源會持久保存為個別檔案，並且所有這些檔案都會與 HAR 檔案一起封存。預設值為 embed，根據 HAR 規格將內容內嵌儲存在 HAR 檔案中。
- setRecordHarMode enum HarMode { FULL, MINIMAL } （選填）#
  
  當設定為 minimal 時，僅記錄從 HAR 路由所需的資訊。這會省略在從 HAR 重播時未使用的尺寸、時間、頁面、Cookie、安全性和其他類型的 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
    
    視訊幀高。
  記錄視訊的尺寸。如果未指定，尺寸將等於縮小到適合 800x800 的 viewport。如果未明確配置 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 （選填）#
  
  變更環境的時區。請參閱 ICU 的 metaZones.txt 以取得支援的時區 ID 清單。預設值為系統時區。
- 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 名稱