Extension automation

Load the extension with nodriver, Playwright, or Selenium using Chrome for Testing.

Choose the browser

Use Google’s official Chrome for Testing binary. Download the version for your platform and keep the browser up to date. It provides a separate Chrome installation for automation. See Google’s Chrome for Testing documentation.

Regular Google Chrome no longer accepts --load-extension, starting with Chrome 137. Chrome for Testing still supports it. See the Chromium team’s announcement. Selecting an installed Chrome channel in your framework does not fix this; point it at the Chrome for Testing executable.

Prepare the extension and profile

Download the extension and extract the ZIP. The extension path must be the directory containing manifest.json, not the ZIP file.
Choose a dedicated profile directory for your automation. Keep that directory between runs so Chrome retains the extension’s settings.
Start the browser with one of the examples below. Set manifest defaults before loading the extension, or open the popup on the first run, enter your API key, and enable solving. For unattended runs, configure the manifest or profile in advance.

Set CHROME_BINARY to the executable inside the Chrome for Testing download, EXTENSION_PATH to the extracted extension directory, and PROFILE_PATH to the dedicated profile directory. Each example opens the hCaptcha demo and waits for a response token. Replace the demo URL and completion condition with your own page’s workflow.

Use one browser process per profile directory. These examples run with a visible window so you can configure the popup. The extension only handles hCaptcha recognition; it does not complete the rest of your page’s form or submit it for you.

nodriver

Install with python -m pip install nodriver. The browser executable and arguments are supported by nodriver’s configuration API.

import asyncio
import os
import time
from pathlib import Path
import nodriver as uc

async def main():
    extension = str(Path(os.environ["EXTENSION_PATH"]).resolve())
    browser = await uc.start(
        browser_executable_path=os.environ["CHROME_BINARY"],
        user_data_dir=str(Path(os.environ["PROFILE_PATH"]).resolve()),
        headless=False,
        browser_args=[f"--load-extension={extension}"],
    )
    try:
        # On the first run, configure the key in the extension popup now.
        await asyncio.to_thread(input, "Press Enter when the extension is ready: ")
        tab = await browser.get(
            "https://accounts.hcaptcha.com/demo?sitekey=4ca1fdb9-c9c9-4495-ba50-c85fc0e7ec1f"
        )
        deadline = time.monotonic() + 180
        while time.monotonic() < deadline:
            token = await tab.evaluate(
                'document.querySelector("[name=h-captcha-response]")?.value || ""'
            )
            if token:
                print("hCaptcha completed")
                return
            await asyncio.sleep(0.5)
        raise TimeoutError("No hCaptcha response within 180 seconds")
    finally:
        browser.stop()

uc.loop().run_until_complete(main())

Remove the interactive prompt once you have configured the saved profile.

Playwright

Install with npm install playwright. Extensions need a persistent browser context. This example follows Playwright’s extension loading pattern and explicitly selects Chrome for Testing instead of regular Chrome.

Save this as automation.mjs and run it with node automation.mjs.

import { chromium } from "playwright";
import { resolve } from "node:path";
import { createInterface } from "node:readline/promises";

const extension = resolve(process.env.EXTENSION_PATH);
const context = await chromium.launchPersistentContext(
  resolve(process.env.PROFILE_PATH),
  {
    executablePath: process.env.CHROME_BINARY,
    headless: false,
    args: [`--load-extension=${extension}`],
  },
);

try {
  // On the first run, configure the key in the extension popup now.
  const prompt = createInterface({
    input: process.stdin,
    output: process.stdout,
  });
  await prompt.question("Press Enter when the extension is ready: ");
  prompt.close();
  const page = await context.newPage();
  await page.goto(
    "https://accounts.hcaptcha.com/demo?sitekey=4ca1fdb9-c9c9-4495-ba50-c85fc0e7ec1f",
  );
  await page.waitForFunction(
    () => Boolean(document.querySelector('[name="h-captcha-response"]')?.value),
    null,
    { timeout: 180_000 },
  );
  console.log("hCaptcha completed");
} finally {
  await context.close();
}

Remove the interactive prompt for subsequent unattended runs. Keep the same persistent profile path.

Selenium

We consider Selenium’s traditional WebDriver approach an outdated choice for hCaptcha automation. Prefer nodriver or Playwright for new integrations. Selenium can expose automation signals that contribute to worse hCaptcha scores or detection. This is a risk assessment, not a guarantee about any framework: the WebDriver standard exposes remote control through navigator.webdriver, and hCaptcha describes behavioral, device, and network signals as inputs to its risk assessment.

If you already use Selenium, install it with python -m pip install selenium. Set the binary location explicitly and use a ChromeDriver version compatible with your Chrome for Testing version. See Selenium’s Chrome options.

import os
from pathlib import Path
from selenium import webdriver
from selenium.webdriver.support.ui import WebDriverWait

extension = str(Path(os.environ["EXTENSION_PATH"]).resolve())
options = webdriver.ChromeOptions()
options.binary_location = os.environ["CHROME_BINARY"]
options.add_argument(f"--load-extension={extension}")
options.add_argument(
    f"--user-data-dir={Path(os.environ['PROFILE_PATH']).resolve()}"
)

driver = webdriver.Chrome(options=options)
try:
    # On the first run, configure the key in the extension popup now.
    input("Press Enter when the extension is ready: ")
    driver.get(
        "https://accounts.hcaptcha.com/demo?sitekey=4ca1fdb9-c9c9-4495-ba50-c85fc0e7ec1f"
    )
    WebDriverWait(driver, 180).until(
        lambda browser: browser.execute_script(
            'return document.querySelector("[name=h-captcha-response]")?.value || ""'
        )
    )
    print("hCaptcha completed")
finally:
    driver.quit()

Troubleshooting

If Chrome ignores the extension, check that you selected the Chrome for Testing executable and that EXTENSION_PATH contains manifest.json. Open chrome://extensions to inspect loading errors.

If the browser loads the extension but no task starts, open its popup and check the enable switch, API key, and available credit. The popup also shows the latest task error. Do not use a fresh temporary profile on every run unless you intend to configure it again.

If the challenge remains unsolved, read the extension guide. Keep the page open while the task runs; repeatedly reloading it can replace the challenge before the result is applied.