class: BrowserType

since: v1.8

BrowserType provides methods to launch a specific browser instance or connect to an existing one. The following is a typical example of using Playwright to drive automation:

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

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

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

import asyncio
from playwright.async_api import async_playwright, Playwright

async def run(playwright: Playwright):
    chromium = playwright.chromium
    browser = await chromium.launch()
    page = await browser.new_page()
    await page.goto("https://example.com")
    # other actions...
    await browser.close()

async def main():
    async with async_playwright() as playwright:
        await run(playwright)
asyncio.run(main())

from playwright.sync_api import sync_playwright, Playwright

def run(playwright: Playwright):
    chromium = playwright.chromium
    browser = chromium.launch()
    page = browser.new_page()
    page.goto("https://example.com")
    # other actions...
    browser.close()

with sync_playwright() as playwright:
    run(playwright)

using Microsoft.Playwright;
using System.Threading.Tasks;

class BrowserTypeExamples
{
    public static async Task Run()
    {
        using var playwright = await Playwright.CreateAsync();
        var chromium = playwright.Chromium;
        var browser = await chromium.LaunchAsync();
        var page = await browser.NewPageAsync();
        await page.GotoAsync("https://www.bing.com");
        // other actions
        await browser.CloseAsync();
    }
}

async method: BrowserType.connect

since: v1.8

returns: <[Browser]>

This method attaches Playwright to an existing browser instance created via BrowserType.launchServer in Node.js.

:::note The major and minor version of the Playwright instance that connects needs to match the version of Playwright that launches the browser (1.2.3 → is compatible with 1.2.x). :::

param: BrowserType.connect.endpoint

since: v1.10

endpoint <[string]>

A Playwright browser websocket endpoint to connect to. You obtain this endpoint via BrowserServer.wsEndpoint.

option: BrowserType.connect.headers

since: v1.11

headers <[Object]<[string], [string]>>

Additional HTTP headers to be sent with web socket connect request. Optional.

option: BrowserType.connect.slowMo

since: v1.10

slowMo <[float]>

Slows down Playwright operations by the specified amount of milliseconds. Useful so that you can see what is going on. Defaults to 0.

option: BrowserType.connect.timeout

since: v1.10

timeout <[float]>

Maximum time in milliseconds to wait for the connection to be established. Defaults to 0 (no timeout).

option: BrowserType.connect.exposeNetwork

since: v1.37

exposeNetwork <[string]>

This option exposes network available on the connecting client to the browser being connected to. Consists of a list of rules separated by comma.

Available rules:

Hostname pattern, for example: example.com, *.org:99, x.*.y.com, *foo.org.
IP literal, for example: 127.0.0.1, 0.0.0.0:99, [::1], [0:0::1]:99.
<loopback> that matches local loopback interfaces: localhost, *.localhost, 127.0.0.1, [::1].

Some common examples:

"*" to expose all network.
"<loopback>" to expose localhost network.
"*.test.internal-domain,*.staging.internal-domain,<loopback>" to expose test/staging deployments and localhost.

async method: BrowserType.connectOverCDP

since: v1.9

returns: <[Browser]>

This method attaches Playwright to an existing browser instance using the Chrome DevTools Protocol.

The default browser context is accessible via [method: Browser.contexts].

:::note Connecting over the Chrome DevTools Protocol is only supported for Chromium-based browsers. :::

:::note This connection is significantly lower fidelity than the Playwright protocol connection via [method: BrowserType.connect]. If you are experiencing issues or attempting to use advanced functionality, you probably want to use [method: BrowserType.connect]. :::

:::warning Playwright maintains a curated list of arguments for launching the browser. If you launch the browser without Playwright and do not pass the exact same arguments, some of Playwright functionality may be broken upon connecting to the browser. :::

Usage

const browser = await playwright.chromium.connectOverCDP('http://localhost:9222');
const defaultContext = browser.contexts()[0];
const page = defaultContext.pages()[0];

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

browser = await playwright.chromium.connect_over_cdp("http://localhost:9222")
default_context = browser.contexts[0]
page = default_context.pages[0]

browser = playwright.chromium.connect_over_cdp("http://localhost:9222")
default_context = browser.contexts[0]
page = default_context.pages[0]

var browser = await playwright.Chromium.ConnectOverCDPAsync("http://localhost:9222");
var defaultContext = browser.Contexts[0];
var page = defaultContext.Pages[0];

param: BrowserType.connectOverCDP.endpointURL

since: v1.11

endpointURL <[string]>

A CDP websocket endpoint or http url to connect to. For example http://localhost:9222/ or ws://127.0.0.1:9222/devtools/browser/387adf4c-243f-4051-a181-46798f4a46f4.

option: BrowserType.connectOverCDP.endpointURL

since: v1.14
langs: js
deprecated: Use the first argument instead.

endpointURL <[string]>

option: BrowserType.connectOverCDP.headers

since: v1.11

headers <[Object]<[string], [string]>>

Additional HTTP headers to be sent with connect request. Optional.

option: BrowserType.connectOverCDP.isLocal

since: v1.58

isLocal <[boolean]>

Tells Playwright that it runs on the same host as the CDP server. It will enable certain optimizations that rely upon the file system being the same between Playwright and the Browser.

option: BrowserType.connectOverCDP.slowMo

since: v1.11

slowMo <[float]>

Slows down Playwright operations by the specified amount of milliseconds. Useful so that you can see what is going on. Defaults to 0.

option: BrowserType.connectOverCDP.timeout

since: v1.11

timeout <[float]>

Maximum time in milliseconds to wait for the connection to be established. Defaults to 30000 (30 seconds). Pass 0 to disable timeout.

option: BrowserType.connectOverCDP.noDefaults

since: v1.60

noDefaults <[boolean]>

When true, Playwright will not apply its default overrides to the existing default browser context. Specifically, [option: Browser.newContext.acceptDownloads] is left at the browser's setting, focus emulation is not enabled, and media emulation options (such as [option: Browser.newContext.colorScheme], [option: Browser.newContext.reducedMotion], [option: Browser.newContext.forcedColors], and [option: Browser.newContext.contrast]) are not applied. Useful when attaching to a user's daily-driver browser where these overrides would interfere with existing browser state. New contexts created via [method: Browser.newContext] are not affected. Defaults to false.

option: BrowserType.connectOverCDP.artifactsDir

since: v1.61

artifactsDir <[path]>

If specified, browser artifacts (such as traces and downloads) are saved into this directory.

method: BrowserType.executablePath

since: v1.8

returns: <[string]>

A path where Playwright expects to find a bundled browser executable.

async method: BrowserType.launch

since: v1.8

returns: <[Browser]>

Returns the browser instance.

Usage

You can use [option: ignoreDefaultArgs] to filter out --mute-audio from default arguments:

const browser = await chromium.launch({  // Or 'firefox' or 'webkit'.
  ignoreDefaultArgs: ['--mute-audio']
});

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

browser = await playwright.chromium.launch( # or "firefox" or "webkit".
    ignore_default_args=["--mute-audio"]
)

browser = playwright.chromium.launch( # or "firefox" or "webkit".
    ignore_default_args=["--mute-audio"]
)

var browser = await playwright.Chromium.LaunchAsync(new() {
    IgnoreDefaultArgs = new[] { "--mute-audio" }
});

Chromium-only Playwright can also be used to control the Google Chrome or Microsoft Edge browsers, but it works best with the version of Chromium it is bundled with. There is no guarantee it will work with any other version. Use [option: executablePath] option with extreme caution.

If Google Chrome (rather than Chromium) is preferred, a Chrome Canary or Dev Channel build is suggested.

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.

option: BrowserType.launch.-inline- = %%-shared-browser-options-list-v1.8-%%

since: v1.8

option: BrowserType.launch.firefoxUserPrefs = %%-js-python-browser-option-firefoxuserprefs-%%

since: v1.8

option: BrowserType.launch.firefoxUserPrefs2 = %%-csharp-java-browser-option-firefoxuserprefs-%%

since: v1.8

option: BrowserType.launch.logger = %%-browser-option-logger-%%

since: v1.8

option: BrowserType.launch.slowMo = %%-browser-option-slowmo-%%

since: v1.8

option: BrowserType.launch.ignoreDefaultArgs = %%-csharp-java-browser-option-ignoredefaultargs-%%

since: v1.8

option: BrowserType.launch.ignoreAllDefaultArgs = %%-csharp-java-browser-option-ignorealldefaultargs-%%

since: v1.9

async method: BrowserType.launchPersistentContext

since: v1.8

returns: <[BrowserContext]>

Returns the persistent browser context instance.

Launches browser that uses persistent storage located at [param: userDataDir] and returns the only context. Closing this context will automatically close the browser.

param: BrowserType.launchPersistentContext.userDataDir

since: v1.8

userDataDir <[path]>

Path to a User Data Directory, which stores browser session data like cookies and local storage. Pass an empty string to create a temporary directory.

More details for Chromium and Firefox. Chromium's user data directory is the parent directory of the "Profile Path" seen at chrome://version.

Note that browsers do not allow launching multiple instances with the same User Data Directory.

:::warning Chromium/Chrome: Due to recent Chrome policy changes, automating the default Chrome user profile is not supported. Pointing userDataDir to Chrome's main "User Data" directory (the profile used for your regular browsing) may result in pages not loading or the browser exiting. Create and use a separate directory (for example, an empty folder) as your automation profile instead. See https://developer.chrome.com/blog/remote-debugging-port for details. :::

option: BrowserType.launchPersistentContext.-inline- = %%-shared-browser-options-list-v1.8-%%

since: v1.8

option: BrowserType.launchPersistentContext.slowMo = %%-browser-option-slowmo-%%

since: v1.8

option: BrowserType.launchPersistentContext.ignoreDefaultArgs = %%-csharp-java-browser-option-ignoredefaultargs-%%

since: v1.8

option: BrowserType.launchPersistentContext.ignoreAllDefaultArgs = %%-csharp-java-browser-option-ignorealldefaultargs-%%

since: v1.9

option: BrowserType.launchPersistentContext.-inline- = %%-shared-context-params-list-v1.8-%%

since: v1.8

option: BrowserType.launchPersistentContext.firefoxUserPrefs = %%-js-python-browser-option-firefoxuserprefs-%%

since: v1.40

option: BrowserType.launchPersistentContext.firefoxUserPrefs2 = %%-csharp-java-browser-option-firefoxuserprefs-%%

since: v1.40

option: BrowserType.launchPersistentContext.clientCertificates = %%-context-option-clientCertificates-%%

since: 1.46

async method: BrowserType.launchServer

since: v1.8
langs: js

returns: <[BrowserServer]>

Returns the browser app instance. You can connect to it via [method: BrowserType.connect], which requires the major/minor client/server version to match (1.2.3 → is compatible with 1.2.x).

Usage

Launches browser server that client can connect to. An example of launching a browser executable and connecting to it later:

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

(async () => {
  const browserServer = await chromium.launchServer();
  const wsEndpoint = browserServer.wsEndpoint();
  // Use web socket endpoint later to establish a connection.
  const browser = await chromium.connect(wsEndpoint);
  // Close browser instance.
  await browserServer.close();
})();

option: BrowserType.launchServer.-inline- = %%-shared-browser-options-list-v1.8-%%

since: v1.8

option: BrowserType.launchServer.firefoxUserPrefs = %%-js-python-browser-option-firefoxuserprefs-%%

since: v1.8

option: BrowserType.launchServer.firefoxUserPrefs2 = %%-csharp-java-browser-option-firefoxuserprefs-%%

since: v1.8

option: BrowserType.launchServer.logger = %%-browser-option-logger-%%

since: v1.8

option: BrowserType.launchServer.host

since: v1.45

host <[string]>

Host to use for the web socket. It is optional and defaults to localhost, accepting connections only from the loopback interface. Pass an explicit address (e.g. 0.0.0.0) to accept connections from the network — be aware this exposes the browser RPC to anything that can reach the listening port.

option: BrowserType.launchServer.port

since: v1.8

port <[int]>

Port to use for the web socket. Defaults to 0 that picks any available port.

option: BrowserType.launchServer.wsPath

since: v1.15

wsPath <[string]>

Path at which to serve the Browser Server. For security, this defaults to an unguessable string.

:::warning Any process or web page (including those running in Playwright) with knowledge of the wsPath can take control of the OS user. For this reason, you should use an unguessable token when using this option. :::

method: BrowserType.name

since: v1.8

returns: <[string]>

Returns browser name. For example: 'chromium', 'webkit' or 'firefox'.

Source: docs/src/api/class-browsertype.md