Playwright Configurations

This page covers advanced Playwright configurations for users already familiar with basic Playwright connections to Browserless. If you haven't set up your basic connection yet, start with our Quick Start guide.

Here are some advanced configurations you can explore:

Advanced Connection Methods

Understanding Connection Types

The basic guide covers connectOverCDP as the recommended method. For detailed comparison of connection methods and when to use each, see our Browser Versions documentation.

Multi-Browser Support

For Firefox and WebKit automation, you must use the connect method since CDP is Chrome-only. Complete examples and browser-specific configurations are available in our Browser Versions guide.

Performance Optimization

Package Optimization

Switch to playwright-core for production deployments to reduce bundle size:

npm install playwright-core

Error Handling and Retry Logic

Implement robust error handling for production environments:

async function withRetry(operation, maxRetries = 3) {  
  for (let attempt = 1; attempt <= maxRetries; attempt++) {  
    try {  
      return await operation();  
    } catch (error) {  
      if (attempt === maxRetries) throw error;  
        
      console.log(`Attempt ${attempt} failed, retrying...`);  
      await new Promise(resolve => setTimeout(resolve, 1000 * attempt));  
    }  
  }  
}

Advanced Session Management

Timeout Configuration

For custom session timeouts and launch parameters, see our comprehensive Launch Options documentation.

Browser Context Configuration

Advanced context options for stealth, geolocation, and viewport settings:

const context = await browser.newContext({  
  extraHTTPHeaders: {  
    'User-Agent': 'Custom User Agent String'  
  },  
  viewport: { width: 1920, height: 1080 },  
  deviceScaleFactor: 1,  
  geolocation: { longitude: -122.4194, latitude: 37.7749 },  
  permissions: ['geolocation']  
});

note

Advanced browser context options (stealth, geolocation, viewport, etc.) are only available when using connectOverCDP. These options are not supported with the standard connect method.

Integration with Browserless Features

Stealth Mode Integration

For comprehensive bot detection bypass, see our Stealth documentation. Basic stealth integration:

const TOKEN = "YOUR_API_TOKEN_HERE";

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

Proxy Configuration

For built-in residential proxies and advanced proxy setups, see our Proxies documentation. Context-level proxy configuration for third-party providers:

const context = await browser.newContext({  
  proxy: {  
    server: "http://proxy-provider.com:8080",  
    username: "username",  
    password: "password"  
  }  
});

PuppeteerSharp Proxy Considerations

When using PuppeteerSharp with the --proxy-server flag in the WebSocket connection URL, calling CreateBrowserContextAsync() creates a new incognito context that does not inherit the proxy settings from the initial browser connection. As a result, requests will default to the Browserless IP instead of routing through your configured proxy.

To ensure the page correctly uses the proxy configured in the WebSocket connection URL, avoid creating a separate browser context. Instead of:

var browserContext = await browser.CreateBrowserContextAsync();
var page = await browserContext.NewPageAsync();

Use this approach:

var page = await browser.NewPageAsync();

This ensures the page inherits the proxy configuration from the WebSocket connection URL.

Version Compatibility

Ensure your Playwright version matches Browserless supported versions. Check the versions compatibility page for current supported versions.

connect vs connectOverCDP

Playwright offers two ways to connect to Browserless. Each method uses a different protocol and unlocks a different feature set.

Method	Playwright API	Browserless Path	Protocol
Playwright native	playwright.chromium.connect({ wsEndpoint })	/chromium/playwright, /firefox/playwright, /webkit/playwright	Playwright's own browser server protocol
CDP mode	playwright.chromium.connectOverCDP(url)	/chromium, /chrome, /	Chrome DevTools Protocol

Playwright Native (connect)

Connect with playwright.chromium.connect() and a /playwright path. This mode uses Playwright's native protocol.

import { chromium } from "playwright-core";

const browser = await chromium.connect(
  "wss://production-sfo.browserless.io/chromium/playwright?token=YOUR_API_TOKEN_HERE"
);
const page = await browser.newPage();
await page.goto("https://example.com");
await browser.close();

CDP Mode (connectOverCDP)

Connect with playwright.chromium.connectOverCDP() and a CDP path. This mode bridges Playwright over the Chrome DevTools Protocol.

import { chromium } from "playwright-core";

const browser = await chromium.connectOverCDP(
  "wss://production-sfo.browserless.io/chromium?token=YOUR_API_TOKEN_HERE"
);
const context = browser.contexts()[0];
const page = await context.newPage();
await page.goto("https://example.com");
await browser.close();

Feature Comparison

Capability	Playwright Native (connect)	CDP Mode (connectOverCDP)
Browser extensions	Not supported	Supported (loaded in default context)
BQL interoperability	Not supported	Supported
Captcha solving	Not supported	Supported
page.route() network interception	Supported	Not supported (use CDP Fetch domain)
APIRequestContext	Supported	Not supported
Firefox / WebKit	Supported	Not supported (Chromium only)
Proxy via browser.newContext()	Supported	Not supported in default context
Proxy via query parameter	Supported	Supported
Multiple independent contexts	Supported	Limited (one default context from browser)
Connection overhead	Lower	Higher

Default context

When you call connectOverCDP, the browser already has one context open. This is the default context. Access it with browser.contexts()[0]. Extensions, cookies, and launch-level settings live in this context. Calling browser.newContext() creates a separate context that does not inherit extensions or launch-level proxy configuration. Use the default context when you need access to those features.

When to Use Each

Use connect (Playwright native) when you need:

• page.route() for request interception, mocking, or blocking
• APIRequestContext for HTTP requests that share browser state
• Firefox or WebKit browser engines
• Lower connection overhead for high-throughput workloads
• Multiple independent browser contexts with separate proxy configs

Use connectOverCDP when you need:

• Browser extensions loaded in the session
• BQL queries against the running browser
• Built-in captcha solving
• Interop with Puppeteer or other CDP-based tools in the same session

Default to CDP mode (connectOverCDP) for most automation tasks. It supports extensions, BQL, and captcha solving. Switch to Playwright native (connect) when you need page.route(), APIRequestContext, or non-Chromium browsers.

Next Steps

Session Management

Learn how to create and manage persistent browser sessions for complex workflows

Stealth Mode

Implement advanced bot detection bypass techniques for more reliable automation

Proxy Configuration

Set up residential and third-party proxies for enhanced privacy and geo-targeting