Setting Up Playwright Automation with HandyBrowsers Profiles

When automating routine tasks across the accounts you manage, it helps to run each one in its own consistent browser environment rather than a bare headless instance. By connecting Playwright directly to a pre-configured HandyBrowsers profile, your scripts inherit that profile's dedicated proxy, cookies, and fingerprint — so automated sessions behave the same way a manual session would.

Prerequisites

Before starting, ensure you have:

• HandyBrowsers desktop app installed and activated.
• A profile created (e.g. Profile ID abc123).
• Node.js (version 18+) installed.
• Playwright installed in your Node.js project: npm install playwright.

Connecting via CDP (Chrome DevTools Protocol)

HandyBrowsers runs a local API server when the desktop app is active. By default, it exposes a CDP debugging port at 9222. You can connect Playwright directly to any profile using this port.

Here is the complete JavaScript code to connect, navigate, and scrape a target site:

const { chromium } = require('playwright');

async function run() {
  // Replace 'abc123' with your actual HandyBrowsers Profile ID
  const profileId = 'abc123';
  const cdpUrl = `ws://127.0.0.1:9222/profile/${profileId}`;

  console.log('Connecting to HandyBrowsers profile...');
  const browser = await chromium.connectOverCDP(cdpUrl);

  // Get the default context already configured with your proxy & cookies
  const context = browser.contexts()[0];
  const page = context ? context.pages()[0] || await context.newPage() : await browser.newPage();

  console.log('Navigating to target site...');
  await page.goto('https://example.com');

  // Take a screenshot to confirm the session loaded correctly
  await page.screenshot({ path: 'verification.png' });
  console.log('Screenshot saved to verification.png');

  await browser.close();
}

run().catch(console.error);

Managing Profiles via Local REST API

You can also automate the creation, launch, and synchronization of profiles via our local REST API. This is ideal for pipelines that manage many of your own profiles at once.

To launch a profile programmatically before connecting Playwright:

const axios = require('axios');

async function launchProfile(profileId) {
  const res = await axios.post(`http://127.0.0.1:9222/api/profiles/${profileId}/start`);
  if (res.data.success) {
    console.log('Profile launched successfully, debug port:', res.data.port);
    return res.data.port;
  }
  throw new Error('Failed to start profile');
}

Best Practices for Reliable Automation

When writing your automation logic, keep these tips in mind:

• Match Proxies to the Account: Use a proxy consistent with the profile's usual location so sessions stay stable.
• Space Out Actions: Avoid instant clicks. Use Playwright's page.mouse.move() or add small delays between actions for more reliable interactions.
• Maintain Cookies: Let HandyBrowsers automatically sync and save your session cookies so your scripts pick up right where a manual session left off.