CAPTCHA Solving

Hyperbrowser automatically solves CAPTCHAs when the solveCaptchas parameter is set to true for session creation.

Node

Puppeteer

import { connect } from "puppeteer-core";
import { Hyperbrowser } from "@hyperbrowser/sdk";
import { config } from "dotenv";

config();

const client = new Hyperbrowser({
  apiKey: process.env.HYPERBROWSER_API_KEY,
});

const main = async () => {
  const session = await client.sessions.create({
    solveCaptchas: true,
  });

  try {
    const browser = await connect({
      browserWSEndpoint: session.wsEndpoint,
      defaultViewport: null,
    });

    const [page] = await browser.pages();

    // Navigate to a website
    console.log("Navigating to Hacker News...");
    await page.goto("https://news.ycombinator.com/");
    const pageTitle = await page.title();
    console.log("Page 1:", pageTitle);
    await page.evaluate(() => {
      console.log("Page 1:", document.title);
    });
  } catch (err) {
    console.error(`Encountered error: ${err}`);
  } finally {
    await client.sessions.stop(session.id);
  }
};

main();

Playwright

import { chromium } from "playwright-core";
import { Hyperbrowser } from "@hyperbrowser/sdk";
import { config } from "dotenv";

config();

const client = new Hyperbrowser({
  apiKey: process.env.HYPERBROWSER_API_KEY,
});

const main = async () => {
  const session = await client.sessions.create({
    solveCaptchas: true,
  });

  try {
    const browser = await chromium.connectOverCDP(session.wsEndpoint);

    const context = browser.contexts()[0];
    const page = await context.newPage();

    // Navigate to a website
    console.log("Navigating to Hacker News...");
    await page.goto("https://news.ycombinator.com/");
    const pageTitle = await page.title();
    console.log("Page 1:", pageTitle);
    await page.evaluate(() => {
      console.log("Page 1:", document.title);
    });
  } catch (err) {
    console.error(`Encountered error: ${err}`);
  } finally {
    await client.sessions.stop(session.id);
  }
};

main();

Python

Puppeteer

import asyncio
from pyppeteer import connect
import os
from dotenv import load_dotenv
from hyperbrowser import AsyncHyperbrowser
from hyperbrowser.models import CreateSessionParams

# Load environment variables from .env file
load_dotenv()

client = AsyncHyperbrowser(api_key=os.getenv("HYPERBROWSER_API_KEY"))


async def main():
    # Create a session and connect to it using Pyppeteer
    session = await client.sessions.create(
        params=CreateSessionParams(
            solve_captchas=True,
        )
    )

    try:
        browser = await connect(
            browserWSEndpoint=session.ws_endpoint, defaultViewport=None
        )

        pages = await browser.pages()
        page = pages[0]

        # Navigate to a website
        print("Navigating to Hacker News...")
        await page.goto("https://news.ycombinator.com/")
        page_title = await page.title()
        print("Page title:", page_title)
        await page.evaluate("() => { console.log('Page 1:', document.title); }")

    except Exception as e:
        print(f"Error: {e}")
    finally:
        await client.sessions.stop(session.id)


# Run the async main function
if __name__ == "__main__":
    asyncio.run(main())

Playwright

import asyncio
from playwright.async_api import async_playwright
import os
from dotenv import load_dotenv
from hyperbrowser import AsyncHyperbrowser
from hyperbrowser.models import CreateSessionParams

# Load environment variables from .env file
load_dotenv()

client = AsyncHyperbrowser(api_key=os.getenv("HYPERBROWSER_API_KEY"))


async def main():
    # Create a session and connect to it using Pyppeteer
    session = await client.sessions.create(
        params=CreateSessionParams(
            solve_captchas=True,
        )
    )

    try:
        async with async_playwright() as p:
            browser = await p.chromium.connect_over_cdp(session.ws_endpoint)
            default_context = browser.contexts[0]
            page = await default_context.new_page()

            # Navigate to a website
            print("Navigating to Hacker News...")
            await page.goto("https://news.ycombinator.com/")
            page_title = await page.title()
            print("Page title:", page_title)
            await page.evaluate("() => { console.log('Page 1:', document.title); }")

    except Exception as e:
        print(f"Error: {e}")
    finally:
        await client.sessions.stop(session.id)


# Run the async main function
if __name__ == "__main__":
    asyncio.run(main())

CAPTCHA solving is only available on PAID plans.

Some sites will require proxy usage enabled in order for the CAPTCHA to be solved properly.

Waiting for CAPTCHA Solve

Captcha solving can take a bit of time, so make sure to implement proper waiting strategies when navigating to pages that might contain CAPTCHAs:

const sleep = (ms) => new Promise((res) => setTimeout(res, ms));

await page.goto("https://news.ycombinator.com/",
    { waitUntil: "networkidle0" }
);
await sleep(20000);

A better approach for this would be to use the session events to know when a CAPTCHA is detected and when it is solved. Here is an example of doing this with a simple function. You can change the values to fit your needs and use another automation library like puppeteer as well.

Node

import { Hyperbrowser } from "@hyperbrowser/sdk";
import { config } from "dotenv";
import { chromium } from "playwright";

config();

const hbClient = new Hyperbrowser({
  apiKey: process.env.HYPERBROWSER_API_KEY,
});

const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));

const MAX_DETECTION_TRIES = 10;
const MAX_SOLVED_TRIES = 30;

const waitForCaptcha = async (sessionId: string, startTimestamp: number) => {
  let solved = false;
  let detected = false;
  let detectionTries = 0;
  let solvedTries = 0;

  console.log("Waiting for captcha detection...");
  while (!detected && detectionTries < MAX_DETECTION_TRIES) {
    const resp = await hbClient.sessions.eventLogs.list(sessionId, {
      startTimestamp,
      types: ["captcha_detected"],
    });
    const data = resp.data;
    detected = data.length > 0;
    detectionTries++;
    await sleep(1000);
  }
  if (detected) {
    console.log("Captcha detected!");
  } else {
    console.log("Captcha not detected!");
    return;
  }

  console.log("Waiting for captcha solving...");
  while (!solved && solvedTries < MAX_SOLVED_TRIES) {
    const resp = await hbClient.sessions.eventLogs.list(sessionId, {
      startTimestamp,
      types: ["captcha_solved"],
    });
    const data = resp.data;
    solved = data.length > 0;
    solvedTries++;
    await sleep(1000);
  }
  if (solved) {
    console.log("Captcha solved!");
  } else {
    console.log("Captcha not solved!");
  }
};

const main = async () => {
  const session = await hbClient.sessions.create({
    solveCaptchas: true,
  });
  console.log("Session Live URL:", session.liveUrl);

  try {
    const browser = await chromium.connectOverCDP(session.wsEndpoint);
    const context = browser.contexts()[0];
    const page = context.pages()[0];
    const startTimestamp = Date.now();
    await page.goto("https://2captcha.com/demo/cloudflare-turnstile");

    await waitForCaptcha(session.id, startTimestamp);
    await sleep(5_000);
  } catch (err) {
    console.error(`Error: ${err}`);
  } finally {
    await hbClient.sessions.stop(session.id);
  }
};

main();

Python

from hyperbrowser import AsyncHyperbrowser
from hyperbrowser.models import SessionEventLogListParams, CreateSessionParams
from playwright.async_api import async_playwright
from dotenv import load_dotenv
import os
import asyncio
import time

load_dotenv()

hb_client = AsyncHyperbrowser(api_key=os.getenv("HYPERBROWSER_API_KEY"))

MAX_DETECTION_TRIES = 10
MAX_SOLVED_TRIES = 30


async def wait_for_captcha(session_id: str, start_timestamp: int):
    solved = False
    detected = False
    detection_tries = 0
    solved_tries = 0

    print("Waiting for captcha detection...")
    while not detected and detection_tries < MAX_DETECTION_TRIES:
        resp = await hb_client.sessions.event_logs.list(
            session_id=session_id,
            params=SessionEventLogListParams(
                start_timestamp=start_timestamp, types=["captcha_detected"]
            ),
        )
        data = resp.data
        detected = len(data) > 0
        detection_tries += 1
        await asyncio.sleep(1)

    if detected:
        print("Captcha detected!")
    else:
        print("Captcha not detected!")
        return

    print("Waiting for captcha solving...")
    while not solved and solved_tries < MAX_SOLVED_TRIES:
        resp = await hb_client.sessions.event_logs.list(
            session_id=session_id,
            params=SessionEventLogListParams(
                start_timestamp=start_timestamp, types=["captcha_solved"]
            ),
        )
        data = resp.data
        solved = len(data) > 0
        solved_tries += 1
        await asyncio.sleep(1)

    if solved:
        print("Captcha solved!")
    else:
        print("Captcha not solved!")


async def main():
    session = await hb_client.sessions.create(
        params=CreateSessionParams(
            solve_captchas=True,
        )
    )
    print("Session Live URL:", session.live_url)

    try:
        async with async_playwright() as p:
            browser = await p.chromium.connect_over_cdp(session.ws_endpoint)
            context = browser.contexts[0]
            page = context.pages[0]
            start_timestamp = int(time.time() * 1000)

            await page.goto("https://2captcha.com/demo/cloudflare-turnstile")

            await wait_for_captcha(session.id, start_timestamp)
            await asyncio.sleep(5)
    except Exception as e:
        print(f"Error: {e}")
    finally:
        await hb_client.sessions.stop(session.id)


if __name__ == "__main__":
    asyncio.run(main())