Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.driver.dev/llms.txt

Use this file to discover all available pages before exploring further.

Playwright is a modern browser automation framework with auto-waiting, powerful selectors, and multi-browser support.

​
Installation

npm install playwright @browsercash/sdk

​
Quick Start

import { chromium } from "playwright";
import BrowsercashSDK from "@browsercash/sdk";

async function run() {
  const client = new BrowsercashSDK({
    apiKey: process.env.DRIVER_API_KEY!,
  });

  // Create a Driver session
  const session = await client.browser.session.create();

  // Connect Playwright via CDP
  const browser = await chromium.connectOverCDP(session.cdpUrl);

  // Get existing context or create new one
  const context = browser.contexts()[0] || (await browser.newContext());
  const page = context.pages()[0] || (await context.newPage());

  // Automate
  await page.goto("https://example.com");
  console.log(await page.title());

  // Cleanup
  await browser.close();
  await client.browser.session.stop({ sessionId: session.sessionId });
}

run().catch(console.error);

​
With Session Options

const session = await client.browser.session.create({
  country: "US",
  type: "consumer_distributed",
  windowSize: "1920x1080",
});

const browser = await chromium.connectOverCDP(session.cdpUrl);

​
Using Existing Contexts

Driver sessions may have a pre-existing browser context. Always check before creating a new one: 
const browser = await chromium.connectOverCDP(session.cdpUrl);

// Use existing context if available
const context = browser.contexts()[0] || (await browser.newContext());
const page = context.pages()[0] || (await context.newPage());

​
With Persistent Profiles

// First run — login and save profile
const session1 = await client.browser.session.create({
  profile: { name: "my-account", persist: true },
});

const browser1 = await chromium.connectOverCDP(session1.cdpUrl);
const page1 = await browser1.newPage();

// Login flow...
await page1.goto("https://example.com/login");
await page1.fill("#email", "[email protected]");
await page1.fill("#password", "password");
await page1.click('button[type="submit"]');

await browser1.close();
await client.browser.session.stop({ sessionId: session1.sessionId });

// Later — session starts already logged in
const session2 = await client.browser.session.create({
  profile: { name: "my-account", persist: true },
});

​
Error Handling

try {
  const browser = await chromium.connectOverCDP(session.cdpUrl);
  // ... automation
} catch (error) {
  if (error.message.includes("Target closed")) {
    // Session may have timed out
    console.log("Session closed, creating new one...");
  }
  throw error;
} finally {
  await client.browser.session.stop({ sessionId: session.sessionId });
}

​
Tips

  • Use page.waitForLoadState('networkidle') for pages with dynamic content
  • Driver sessions support all Playwright features including screenshots, PDFs, and tracing
  • For long-running tasks, monitor session status and handle reconnection
  • Use browser.close() to end your Playwright connection. Unlike Puppeteer’s browser.disconnect(), this properly closes the CDP connection while the Driver session can still be stopped separately via the API