Skip to main content
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.BROWSER_API_KEY!,
  });

  // Create a Browser Cash 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

Browser Cash 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
  • Browser Cash 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 Browser Cash session can still be stopped separately via the API