Connecting Playwright

We support Playwright's Chrome DevTools Protocol (CDP) connection method, which provides a reliable way to connect to Browserless. This method is similar to how Puppeteer operates and is well-suited for most automation tasks. Playwright's Connect method is also supported, but more restrictive.

Once you have gotten your API key from the Browserless dashboard, you can connect Playwright to Browserless.

Below are the examples of javascript and python scripts using browserless:

Javascript

import { chromium } from "playwright-core";

// Connecting to Chrome locally
const browser = await chromium.launch();

// Connecting to Chrome via Browserless
const browser = await chromium.connectOverCDP(
  `wss://production-sfo.browserless.io?token=${TOKEN}`
);

Python

from playwright.sync_api import sync_playwright

with sync_playwright() as p:
    # Connecting to Chrome locally
    browser = p.chromium.launch()

    # Connecting to Chrome via Browserless
    browser = p.chromium.connect_over_cdp(
        f"wss://production-sfo.browserless.io?token={TOKEN}"
    )

Java

package org.example;

import com.microsoft.playwright.*;

public class Main {
  public static void main(String[] args) {
    try (Playwright playwright = Playwright.create()) {
      // Connecting to Chrome locally
      Browser browserLocal = playwright.chromium().launch();

      // Connecting to Chrome via Browserless
      Browser browser = playwright.chromium().connectOverCDP(
        String.format("wss://production-sfo.browserless.io?token=%s", TOKEN)
      );
    }
  }
}

C#

using Microsoft.Playwright;

namespace PlaywrightExample
{
    class Program
    {
        public static async Task Main(string[] args)
        {
            using var playwright = await Playwright.CreateAsync();
            // Connecting to Chrome locally
            var browserLocal = await playwright.Chromium.LaunchAsync();

            // Connecting to Chrome via Browserless
            var browser = await playwright.Chromium.ConnectOverCDPAsync(
                $"wss://production-sfo.browserless.io?token={TOKEN}"
            );
        }
    }
}

Migrating from local Chrome to Browserless

Let's take a simple example of using playwright in a script. To migrate from local Chrome to Browserless, you need to change from chromium.launch() to chromium.connectOverCDP() with a WebSocket endpoint.

Optional optimization: You can also switch from playwright to playwright-core (which doesn't include browser binaries) since you'll be connecting to remote browsers instead of launching local ones:

Before browserless

import { chromium } from "playwright";

const browser = await chromium.launch();
const page = await browser.newPage();
// ...

After browserless

import { chromium } from "playwright-core";

const browser = await chromium.connectOverCDP(
  `wss://production-sfo.browserless.io?token=YOUR_API_TOKEN_HERE`
);
const page = await browser.newPage();
// ...

Connection Methods

Browserless supports two connection methods for Playwright: connectOverCDP and connect.

connectOverCDP Method (Recommended)

The connectOverCDP method uses Chrome's DevTools Protocol and is the recommended approach for connecting to Browserless. This method allows you to experience advanced Browserless capabilities like stealth flag, in-built proxies, and more. It provides a stable and reliable connection for most automation tasks.

Note: connectOverCDP is only supported by Chrome-based browsers. For other browsers like Firefox or WebKit, you must use the connect method.

Example: Take a screenshot with Playwright using Browserless

import { chromium } from "playwright-core";

// Connect to Browserless using CDP (recommended method)
const browser = await chromium.connectOverCDP(
  "wss://production-sfo.browserless.io?token=YOUR_API_TOKEN_HERE"
);
const context = await browser.newContext();
const page = await context.newPage();

// Navigate to the target website
await page.goto("https://www.example.com/");
// Take a screenshot and save it locally
await page.screenshot({ path: "screenshot.png" });

// Clean up resources
await browser.close();

connect Method

Playwright's connect method uses its built-in browser-server protocol. While this method can be faster in some cases, it has some limitations:

• Your client's Playwright version must match the server's version
• Limited support for Browserless advanced features such as the stealth flag, in-built proxies, and more

Here's how to use the connect method:

import { chromium } from "playwright-core";

// Connect using Playwright's built-in protocol
const browser = await chromium.connect(
  `wss://production-sfo.browserless.io/chrome/playwright?token=${TOKEN}`
);

Warning: To avoid errors with no apparent reason, please make sure your playwright version is compatible with one of these versions.

Using Other Browsers

Since connectOverCDP is only supported by Chrome-based browsers, you must use the connect method for Firefox and WebKit. While Chrome is recommended for most use cases, Browserless also supports these other browsers:

Firefox Example

import { firefox } from "playwright-core";

// Connect to Firefox using the connect method (required for non-Chrome browsers)
const browser = await firefox.connect(
  `wss://production-sfo.browserless.io/firefox/playwright?token=${TOKEN}`
);
const context = await browser.newContext();
const page = await context.newPage();

// Navigate to target website
await page.goto("https://www.example.com/");
// Take a screenshot with Firefox
await page.screenshot({ path: "firefox-screenshot.png" });

// Clean up resources
await browser.close();

WebKit Example

import { webkit } from "playwright-core";

// Connect to WebKit using the connect method (required for non-Chrome browsers)
const browser = await webkit.connect(
  `wss://production-sfo.browserless.io/webkit/playwright?token=${TOKEN}`
);
const context = await browser.newContext();
const page = await context.newPage();

// Navigate to target website
await page.goto("https://www.example.com/");
// Take a screenshot with WebKit
await page.screenshot({ path: "webkit-screenshot.png" });

// Clean up resources
await browser.close();

Important: When using Firefox or WebKit, you must use the connect method as CDP is only supported by Chrome-based browsers.

Using 3rd Party Proxies with Playwright

When using Playwright with browserless, you can set up a 3rd party proxy by providing proxy configuration to the newContext() method:

import { chromium } from "playwright-core";

// Connect to Browserless using CDP
const browser = await chromium.connectOverCDP(
  "wss://production-sfo.browserless.io?token=YOUR_API_TOKEN_HERE"
);

// Create a new context with proxy configuration
const context = await browser.newContext({
  proxy: {
    server: "http://domain:port",    // Your proxy server address
    username: "username",            // Proxy authentication username
    password: "password",            // Proxy authentication password
  },
});
const page = await context.newPage();

// Visit a site that shows your IP address to verify proxy is working
await page.goto("https://icanhazip.com/");
console.log(await page.content());

await browser.close();

This approach applies the proxy configuration at the context level, which means all pages created from that context will use the specified proxy. For more detailed information about using proxies with Playwright, see our Proxies documentation.