Skip to Content
Getting StartedPlaywright

Getting Started with Playwright

Launch BotBrowser with Playwright using profile-first configuration and framework-specific cleanup.

Prerequisites

  • BotBrowser installed. See Installation.
  • Node.js 18+.
  • playwright-core installed.
  • Profile file (.enc for production).

Quick Start

npm init -y
npm install playwright-core
import { chromium } from "playwright-core";
 
const browser = await chromium.launch({
  executablePath: process.env.BOTBROWSER_EXEC_PATH,
  headless: true,
  args: [
    `--bot-profile=${process.env.BOT_PROFILE_PATH}`,
    "--proxy-server=socks5://user:pass@proxy.example.com:1080",
  ],
});
 
const page = await browser.newPage();
 
// Playwright-specific cleanup before first navigation
await page.addInitScript(() => {
  delete window.__playwright__binding__;
  delete window.__pwInitScripts;
});
 
await page.goto("https://example.com");
await browser.close();

How It Works

Playwright integration has one key requirement in addition to normal BotBrowser launch:

  1. Launch with BotBrowser flags in args (--bot-profile, optional --proxy-server).
  2. Run addInitScript() before first navigation to remove Playwright-injected bindings.
  3. Keep profile-managed identity surfaces unchanged (no custom viewport overrides unless required).

For shared automation guidance (runtime consistency, bot-script fallback, troubleshooting baseline), see Automation Consistency.

Common Scenarios

Geo override with Playwright

const browser = await chromium.launch({
  executablePath: process.env.BOTBROWSER_EXEC_PATH,
  headless: true,
  args: [
    `--bot-profile=${process.env.BOT_PROFILE_PATH}`,
    "--proxy-server=socks5://user:pass@proxy.example.com:1080",
    "--bot-config-timezone=Europe/Berlin",
    "--bot-config-locale=de-DE",
    "--bot-config-languages=de-DE,de,en-US,en",
  ],
});

Per-context fingerprint assignment

const browser = await chromium.launch({
  executablePath: process.env.BOTBROWSER_EXEC_PATH,
  headless: true,
  args: [`--bot-profile=${process.env.BOT_PROFILE_PATH}`],
});
 
const client = await browser.newBrowserCDPSession();
 
// Snapshot existing context IDs
const { browserContextIds: before } = await client.send("Target.getBrowserContexts");
const context = await browser.newContext();
const { browserContextIds: after } = await client.send("Target.getBrowserContexts");
const contextId = after.filter(id => !before.includes(id))[0];
 
await client.send("BotBrowser.setBrowserContextFlags", {
  browserContextId: contextId,
  botbrowserFlags: [
    "--bot-profile=/path/to/another.enc",
    "--proxy-server=socks5://user:pass@proxy2.example.com:1080",
  ],
});

Troubleshooting / FAQ

ProblemSolution
Playwright bindings still visibleEnsure addInitScript() runs before first page.goto().
Geo values do not match proxyPass proxy via args using --proxy-server, not framework proxy options.
Launch failsVerify BOTBROWSER_EXEC_PATH points to BotBrowser binary and has execute permission.
Multiple instances conflictProvide unique --user-data-dir per instance.

Next Steps

Related documentation: Examples  | Per-Context Fingerprint

Legal Disclaimer & Terms of Use  • Responsible Use Guidelines . BotBrowser is for authorized fingerprint protection and privacy research only.

InstallationPuppeteer