Puppeteer (Node.js) Module

Uses Puppeteer to automatically solve CAPTCHAs. Supports image clicking, slider dragging, and other CAPTCHA types. Can detect the CAPTCHA type on the page automatically.

Latest Version

Module Version	Download	Changes
0.4	npm · 0.4	Global update, automatic CAPTCHA detection auto(), added AWS WAF

Installation

The module is published on npm:

npm install capguru puppeteer

const { CaptchaSolver, CapGuruFatalError } = require('capguru');

Update to the latest version:

npm install capguru@latest

Installation without npm

Download the archive from the version table, copy the capguru folder into your project and install Puppeteer:

npm install puppeteer

Then import it with a relative path: require('./capguru').

Usage

Import CaptchaSolver from the package. Create the solver before navigating to the page with the CAPTCHA and call await solver.setup(). Then open the page and call await solver.auto() — the module will find the CAPTCHA and solve it. If you know the CAPTCHA type in advance, you can call the specific method directly.

const puppeteer = require('puppeteer');
const { CaptchaSolver, CapGuruFatalError } = require('capguru');

(async () => {
  const browser = await puppeteer.launch({ headless: false });
  const page = await browser.newPage();

  const solver = new CaptchaSolver({
    page,
    apiKey: 'YOUR_CAPGURU_API_KEY',
    debug: true,
    attempts: 5,
  });
  await solver.setup();

  await page.goto('https://example.com/with-captcha');

  try {
    const kind = await solver.auto(30);
    console.log('Captcha:', kind || 'not found');
  } catch (e) {
    if (e instanceof CapGuruFatalError) console.log('API key or balance problem:', e.message);
    else console.log('Not solved:', e.message);
  } finally {
    await browser.close();
  }
})();

Why the solver is created before navigation

When created, the solver starts capturing the CAPTCHA images loaded by the browser and switches hCaptcha to English. If you create it after page.goto(), images from the first load will be missed and hCaptcha may stay in the site's language.

Methods

Automatic:

  await solver.auto(30);      // find and solve the CAPTCHA, returns its type or null
  await solver.detect();      // only detect the type, without solving
  await solver.setup();       // preparation, call before page.goto()

For a specific type:

  await solver.solveRecaptcha2();
  await solver.solveHcaptcha();
  await solver.solveOther();
  await solver.solveGeetest();
  await solver.solveFuncaptcha();
  await solver.solveTiktok();
  await solver.solveAws();

auto() and detect() return the CAPTCHA type:

Value	CAPTCHA
recaptcha2	reCAPTCHA v2
hcaptcha	hCaptcha
yandex	Other
geetest	GeeTest v3 / v4
funcaptcha	FunCaptcha (Arkose Labs)
tiktok	TikTok
aws	AWS WAF
null	No CAPTCHA found within the timeout

auto() parameters:

Parameter	Type	Default	Description
timeout	number	30	How many seconds to wait for a CAPTCHA to appear
poll	number	0.5	How often to check the page, in seconds

Supported CAPTCHA Types

reCaptcha2	FunCaptcha	TikTok	GeeTest	hCaptcha	AWS WAF	Other
Yes	Yes	Yes	Yes	Yes	Yes	Yes

Constructor Parameters

Parameter	Type	Default	Description
page	Page	—	Puppeteer page instance
apiKey	string	—	Cap.Guru API key
server	string	'https://api.cap.guru'	API server URL
attempts	number	5	Max number of solving attempts
debug	boolean	false	Enable debug logging
selector	string	''	CSS selector for the CAPTCHA container

Requirements

• Puppeteer 24 or 25
• Node.js 18+ (Puppeteer 25 requires Node.js 22.12+)

Error Handling

An invalid API key or zero balance throws CapGuruFatalError — the module stops retrying immediately. If the CAPTCHA could not be solved after all attempts, an Error is thrown. CapGuruFatalError is a subclass of Error, so check it first:

const { CapGuruFatalError } = require('capguru');

try {
  const kind = await solver.auto(30);
  console.log('Captcha:', kind || 'not found');
} catch (e) {
  if (e instanceof CapGuruFatalError) {
    console.log('API key or balance problem:', e.message);
  } else if (e.message.includes('ERROR_CAPTCHA_UNSOLVABLE')) {
    console.log('CAPTCHA could not be solved after all attempts');
  }
}