Skip to main content

class: BrowserType

Added in: 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 copilotbrowser to drive automation:

const { chromium } = require('copilotbrowser');  // 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.copilotbrowser.*;

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

async def run(copilotbrowser: copilotbrowser):
    chromium = copilotbrowser.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_copilotbrowser() as copilotbrowser:
        await run(copilotbrowser)
asyncio.run(main())
from copilotbrowser.sync_api import sync_copilotbrowser, copilotbrowser

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

with sync_copilotbrowser() as copilotbrowser:
    run(copilotbrowser)
using Microsoft.copilotbrowser;
using System.Threading.Tasks;

class BrowserTypeExamples
{
    public static async Task Run()
    {
        using var copilotbrowser = await copilotbrowser.CreateAsync();
        var chromium = copilotbrowser.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​

Added in: v1.8 Returns: Browser

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

note

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

param: BrowserType.connect.wsEndpoint​

Added in: v1.10

  • wsEndpoint <string>

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

option: BrowserType.connect.headers​

Added in: v1.11

  • headers <Object<string, string>>

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

option: BrowserType.connect.slowMo​

Added in: v1.10

  • slowMo <float>

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

option: BrowserType.connect.logger​

Added in: v1.14

Languages: JavaScript

⚠️ Deprecated. The logs received by the logger are incomplete. Please use tracing instead.

  • logger <Logger>

Logger sink for copilotbrowser logging. Optional.

option: BrowserType.connect.timeout​

Added in: 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​

Added in: 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:

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

Some common examples:

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

async method: BrowserType.connectOverCDP​

Added in: v1.9 Returns: Browser

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

The default browser context is accessible via 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 copilotbrowser protocol connection via BrowserType.connect(). If you are experiencing issues or attempting to use advanced functionality, you probably want to use BrowserType.connect().

Usage

const browser = await copilotbrowser.chromium.connectOverCDP('http://localhost:9222');
const defaultContext = browser.contexts()[0];
const page = defaultContext.pages()[0];
Browser browser = copilotbrowser.chromium().connectOverCDP("http://localhost:9222");
BrowserContext defaultContext = browser.contexts().get(0);
Page page = defaultContext.pages().get(0);
browser = await copilotbrowser.chromium.connect_over_cdp("http://localhost:9222")
default_context = browser.contexts[0]
page = default_context.pages[0]
browser = copilotbrowser.chromium.connect_over_cdp("http://localhost:9222")
default_context = browser.contexts[0]
page = default_context.pages[0]
var browser = await copilotbrowser.Chromium.ConnectOverCDPAsync("http://localhost:9222");
var defaultContext = browser.Contexts[0];
var page = defaultContext.Pages[0];

param: BrowserType.connectOverCDP.endpointURL​

Added in: 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​

Added in: v1.14

Languages: JavaScript

⚠️ Deprecated. Use the first argument instead.

  • endpointURL <string>

option: BrowserType.connectOverCDP.headers​

Added in: v1.11

  • headers <Object<string, string>>

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

option: BrowserType.connectOverCDP.isLocal​

Added in: v1.58

  • isLocal <boolean>

Tells copilotbrowser 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 copilotbrowser and the Browser.

option: BrowserType.connectOverCDP.logger​

Added in: v1.14

Languages: JavaScript

⚠️ Deprecated. The logs received by the logger are incomplete. Please use tracing instead.

  • logger <Logger>

Logger sink for copilotbrowser logging. Optional.

option: BrowserType.connectOverCDP.slowMo​

Added in: v1.11

  • slowMo <float>

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

option: BrowserType.connectOverCDP.timeout​

Added in: 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.

method: BrowserType.executablePath​

Added in: v1.8 Returns: string

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

async method: BrowserType.launch​

Added in: v1.8 Returns: Browser

Returns the browser instance.

Usage

You can use 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 copilotbrowser.chromium.launch( # or "firefox" or "webkit".
    ignore_default_args=["--mute-audio"]
)
browser = copilotbrowser.chromium.launch( # or "firefox" or "webkit".
    ignore_default_args=["--mute-audio"]
)
var browser = await copilotbrowser.Chromium.LaunchAsync(new() {
    IgnoreDefaultArgs = new[] { "--mute-audio" }
});

Chromium-only copilotbrowser 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 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-%%​

Added in: v1.8

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

Added in: v1.8

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

Added in: v1.8

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

Added in: v1.8

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

Added in: v1.8

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

Added in: v1.8

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

Added in: v1.9

async method: BrowserType.launchPersistentContext​

Added in: v1.8 Returns: BrowserContext

Returns the persistent browser context instance.

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

param: BrowserType.launchPersistentContext.userDataDir​

Added in: 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-%%​

Added in: v1.8

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

Added in: v1.8

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

Added in: v1.8

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

Added in: v1.9

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

Added in: v1.8

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

Added in: v1.40

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

Added in: v1.40

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

  • since: 1.46

async method: BrowserType.launchServer​

Added in: v1.8

Languages: JavaScript Returns: BrowserServer

Returns the browser app instance. You can connect to it via 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('copilotbrowser');  // 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-%%​

Added in: v1.8

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

Added in: v1.8

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

Added in: v1.8

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

Added in: v1.8

option: BrowserType.launchServer.host​

Added in: v1.45

  • host <string>

Host to use for the web socket. It is optional and if it is omitted, the server will accept connections on the unspecified IPv6 address (::) when IPv6 is available, or the unspecified IPv4 address (0.0.0.0) otherwise. Consider hardening it with picking a specific interface.

option: BrowserType.launchServer.port​

Added in: v1.8

  • port <int>

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

option: BrowserType.launchServer.wsPath​

Added in: 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 copilotbrowser) 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​

Added in: v1.8 Returns: string

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