Your Puppeteer script fills in the form, clicks "I'm not a robot", and stops there. Each time I tried that in headless Chrome tonight, the click didn't tick the box. It opened the image grid, and the script was now expected to find fire hydrants.
It doesn't have to. The site never checks the checkbox. It checks a token. When a person solves the widget, reCAPTCHA writes a token into a hidden g-recaptcha-response field, and the site's backend verifies that token with Google. A solving API returns the same kind of token from two inputs: the sitekey and the page URL. So in Puppeteer the job is to find the sitekey, get a token, put it where the form reads it, and submit.
This post does that on Google's own checkbox demo with Node 22.18 and Puppeteer 25.14.0, which downloads its own headless Chrome 155. (Puppeteer 25 needs Node 22.12 or newer.) No puppeteer-extra, no plugin, just puppeteer. Every output below comes from runs on 2026-10-18. The Python and Selenium version covers the API side in more detail, so this one sticks to the Puppeteer parts.
What the click does in headless Chrome
The checkbox sits inside an iframe. In Puppeteer you get that iframe as a Frame with contentFrame(), then click inside it:
// click-checkbox.mjs: what a plain click on "I'm not a robot" does in headless Puppeteer.
// Needs: Node 22.12+ (for Puppeteer 25) and npm i puppeteer
import puppeteer from "puppeteer";
const browser = await puppeteer.launch({ headless: true });
try {
const page = await browser.newPage();
await page.goto("https://www.google.com/recaptcha/api2/demo", { waitUntil: "networkidle2" });
console.log("navigator.webdriver:", await page.evaluate(() => navigator.webdriver));
// The checkbox is inside the anchor iframe: get that frame with contentFrame(), then click in it.
const anchorHandle = await page.waitForSelector('iframe[title="reCAPTCHA"]');
const anchor = await anchorHandle.contentFrame();
await anchor.click("#recaptcha-anchor");
await new Promise((resolve) => setTimeout(resolve, 5_000));
const checked = await anchor.$eval("#recaptcha-anchor", (el) => el.getAttribute("aria-checked"));
console.log("aria-checked:", checked);
const bframeHandle = await page.$('iframe[src*="/bframe"]'); // the challenge popup
console.log("challenge iframe:", await bframeHandle.evaluate((f) => {
const box = f.getBoundingClientRect();
return `${box.width}x${box.height}, ${getComputedStyle(f).visibility}`;
}));
const bframe = await bframeHandle.contentFrame();
const task = await bframe.$eval(".rc-imageselect-desc-wrapper", (el) => el.innerText)
.catch(() => "(no image grid)");
console.log("challenge says:", task.replace(/\s+/g, " "));
const token = await page.$eval("#g-recaptcha-response", (t) => t.value);
console.log("g-recaptcha-response:", token.length, "chars");
} finally {
await browser.close();
}
$ node click-checkbox.mjs
navigator.webdriver: true
aria-checked: false
challenge iframe: 400x580, visible
challenge says: Select all images with a fire hydrant Click verify once there are none left.
g-recaptcha-response: 0 chars
The box stayed unchecked, the 400x580 challenge iframe opened, and the response field is still empty. Six runs tonight, six image challenges: fire hydrants three times, plus motorcycles, stairs and crosswalks. You could start clicking tiles, but then you're writing an image classifier to fill in one form field. Skip the widget and fill the field.
Step 1: find the widget with page.frames()
Every rendered widget gets an anchor iframe. Its URL carries the sitekey as k= and the widget type as size=. page.frames() lists every frame on the page, cross-origin ones included, so this works even when the page builds the widget from JavaScript and the HTML has no data-sitekey. The script below waits for the first anchor with page.waitForFrame(), logs every anchor it finds, and takes the first one whose size isn't invisible.
Logging all of them paid off on Google's other demo, on recaptcha-demo.appspot.com, which loads two:
00:29:27Z anchor k=6LfW6wATAAAAAHLqO2pb8bDBahxlMxNdo9g947u9 size=normal /recaptcha/api2/anchor
00:29:27Z anchor k=6Le80pApAAAAANg24CMbhL_U2PASCW_JUnq5jPys size=invisible /recaptcha/enterprise/anchor
The second one is an Enterprise score key that the form doesn't use. Code that grabs the first iframe[src*="recaptcha"] works until the page loads them in the other order. Invisible v2 and v3 both report size=invisible and need different parameters, so the script stops when that's all it finds. For invisible v2, the invisible reCAPTCHA v2 walkthrough sends invisible=1. reCAPTCHA v3 takes version=v3 and the page's action instead, as the v3 solver post shows.
The script also reads data-sitekey from .g-recaptcha and logs whether it matches k=. On both demos it did. If they ever differ, trust the anchor, because it's what reCAPTCHA actually rendered.
One more frames detail. anchor.parentFrame() is the document that shows the widget. On both demos that's the page itself. If a site puts its form in an iframe, it's that iframe, and the reCAPTCHA v2 guide says to send the iframe's URL as pageurl. The script uses that frame for pageurl, for the token and for the submit, so it follows the widget. I only ran it on top-level widgets, though.
Step 2: get a token with fetch
Node 18 and later have fetch built in, so the API side needs no packages. It's a standard reCAPTCHA v2 task on the 2Captcha-style in.php/res.php API: method=userrecaptcha, the sitekey as googlekey, the pageurl, and json=1. Wait 15 seconds, then poll every 5. A task that isn't done after 180 seconds, or that comes back ERROR_CAPTCHA_UNSOLVABLE, gets one new task.
// solve-recaptcha.mjs: get a reCAPTCHA v2 checkbox token from an in.php/res.php API.
// Node 18+ (built-in fetch), no packages. Set CAPTCHAAI_KEY in the environment.
const API = "https://ocr.captchaai.com";
const KEY = (process.env.CAPTCHAAI_KEY ?? "").trim();
const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
export const log = (...args) => console.log(new Date().toISOString().slice(11, 19) + "Z", ...args);
async function call(path, params) {
const r = await fetch(`${API}/${path}`, {
method: "POST",
body: new URLSearchParams({ ...params, key: KEY, json: "1" }),
});
return r.json(); // { status, request } because of json=1
}
// One task: submit, wait 15 s, then poll every 5 s. Returns the token, or null if the task failed.
async function oneTask(sitekey, pageurl, timeout) {
const sub = await call("in.php", { method: "userrecaptcha", googlekey: sitekey, pageurl });
if (sub.status !== 1) throw new Error(`in.php: ${sub.request}`); // wrong key, no free thread, bad sitekey
const id = String(sub.request); // the id arrives as a number
const started = Date.now();
log(`task ${id} submitted`);
await sleep(15_000);
while (Date.now() - started < timeout) {
const res = await call("res.php", { action: "get", id });
const secs = ((Date.now() - started) / 1000).toFixed(1);
if (res.status === 1) {
log(`task ${id} solved in ${secs}s`);
return res.request;
}
if (res.request === "ERROR_CAPTCHA_UNSOLVABLE") {
log(`task ${id}: ERROR_CAPTCHA_UNSOLVABLE after ${secs}s`);
return null;
}
if (res.request !== "CAPCHA_NOT_READY") throw new Error(`res.php: ${res.request}`); // sic, no T
await sleep(5_000);
}
log(`task ${id} not solved in ${timeout / 1000}s`);
return null;
}
// A token task can be slow or fail, so a failed task gets one new task before we give up.
export async function solveRecaptchaV2(sitekey, pageurl, { timeout = 180_000, tasks = 2 } = {}) {
if (!KEY) throw new Error("Set CAPTCHAAI_KEY to your API key first");
for (let i = 0; i < tasks; i++) {
const token = await oneTask(sitekey, pageurl, timeout);
if (token) return token;
}
throw new Error(`no token from ${tasks} tasks`);
}
Two details from the live API: the task id arrives as a JSON number ({"status":1,"request":5608577418} in a raw reply tonight), and CAPCHA_NOT_READY really has no T. Apart from that and ERROR_CAPTCHA_UNSOLVABLE, any error stops the script, because retrying a wrong key or a bad sitekey won't fix it. The post on the submit-and-poll loop lists every reply I got from the live API and which ones deserve a retry.
Step 3: page.type() can't fill the token field
The token goes in the g-recaptcha-response textarea. reCAPTCHA adds it to the widget's document, not to the iframe, and hides it with display: none. Selenium's send_keys throws on it. Puppeteer's page.type() is quieter. It doesn't throw, and it doesn't type either:
$ node probe-type.mjs
textarea display: none
page.type(SEL, "abc") -> value ""
page.evaluate(el.value = "abc") -> value "abc"
Set .value from inside the page with evaluate() instead. The script fills every textarea named g-recaptcha-response. That's right for a page with one widget. With two widgets in two forms, fill only the one in your form.
Google's demo also declares data-callback="onSuccess". The script doesn't call it, and the demo's backend didn't need it. On a real site, if the submit button stays disabled after the injection, the callback is often what enables it. The callback post shows how to find it and call it.
Step 4: submit and wait for the navigation
click() resolves once the click has happened, not once the next page has loaded. If you await the click and only then call waitForNavigation(), a fast response can land in between, and the wait times out. The script starts both together with Promise.all. If the form posts with fetch and the page never reloads, wait for the site's own success element instead.
The whole script
// recaptcha-v2-puppeteer.mjs: solve a reCAPTCHA v2 checkbox in Puppeteer with a solving API, no plugin.
// Needs: Node 22.12+ (for Puppeteer 25) and npm i puppeteer; solve-recaptcha.mjs sits next to it
// CAPTCHAAI_KEY=... node recaptcha-v2-puppeteer.mjs [page url] [token to test with]
import puppeteer from "puppeteer";
import { log, solveRecaptchaV2 } from "./solve-recaptcha.mjs";
const url = process.argv[2] ?? "https://www.google.com/recaptcha/api2/demo";
const testToken = process.argv[3]; // skip the API and submit this instead
const ANCHOR = /\/recaptcha\/(api2|enterprise)\/anchor\?/; // one anchor frame per rendered widget
const browser = await puppeteer.launch({ headless: true });
try {
const page = await browser.newPage();
await page.goto(url, { waitUntil: "networkidle2" });
// 1. Find the widget. Its anchor frame URL carries the sitekey (k=) and the widget size.
await page.waitForFrame((f) => ANCHOR.test(f.url()), { timeout: 20_000 });
const anchors = page.frames().filter((f) => ANCHOR.test(f.url()));
for (const f of anchors) {
const u = new URL(f.url());
log(`anchor k=${u.searchParams.get("k")} size=${u.searchParams.get("size")} ${u.pathname}`);
}
const anchor = anchors.find((f) => new URL(f.url()).searchParams.get("size") !== "invisible");
if (!anchor) throw new Error("no checkbox widget: size=invisible means invisible v2 or v3");
const sitekey = new URL(anchor.url()).searchParams.get("k");
const host = anchor.parentFrame(); // the document that shows the widget
const declared = await host.$eval(".g-recaptcha", (el) => el.dataset.sitekey).catch(() => null);
log(`sitekey ${sitekey} (data-sitekey: ${declared === sitekey ? "same" : declared ?? "none"})`);
// 2. Get a token. pageurl is the URL of the document that shows the widget.
const token = testToken ?? (await solveRecaptchaV2(sitekey, host.url()));
log(`token ${token.slice(0, 20)}... (${token.length} chars)`);
// 3. Put it in the hidden textarea, in the widget's document, not in the iframe.
await host.evaluate((t) => {
for (const el of document.querySelectorAll('textarea[name="g-recaptcha-response"]')) el.value = t;
}, token);
// 4. Submit. Start waiting for the navigation before the click that causes it.
await Promise.all([
host.waitForNavigation({ waitUntil: "domcontentloaded" }),
host.click("form [type=submit]"),
]);
// Google's demo answers with one of two lines; the appspot demo prints its siteverify result.
// On your own site, wait for its own success signal instead.
const lines = (await host.$eval("body", (b) => b.innerText)).split("\n").map((s) => s.trim());
const said = lines.filter((s) => /Hooray|verify that you are not a robot|'(success|hostname)'/.test(s));
log("page says:", said.join(" | ") || "(none of the lines I look for)");
} catch (err) {
log("FAILED:", err.message);
process.exitCode = 1;
} finally {
await browser.close();
}
With the key set and no arguments, it solves Google's demo and submits:
$ CAPTCHAAI_KEY=... node recaptcha-v2-puppeteer.mjs
00:34:06Z anchor k=6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ- size=normal /recaptcha/api2/anchor
00:34:06Z sitekey 6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ- (data-sitekey: same)
00:34:06Z task 5608583421 submitted
00:35:03Z task 5608583421 solved in 57.3s
00:35:03Z token 0cAFcWeA4jcxIytEZCQ_... (2532 chars)
00:35:04Z page says: Verification Success... Hooray!
Verification Success... Hooray! is the demo's answer once its backend has verified the token with Google. That was my fastest run on this demo. The next section has all of them.
The second argument is a token to submit instead of solving, so you can test the page side for free. A fake one gets the demo's rejection:
$ node recaptcha-v2-puppeteer.mjs https://www.google.com/recaptcha/api2/demo 03AFcWeA-not-a-real-token
00:32:57Z anchor k=6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ- size=normal /recaptcha/api2/anchor
00:32:57Z sitekey 6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ- (data-sitekey: same)
00:32:57Z token 03AFcWeA-not-a-real-... (25 chars)
00:32:57Z page says: Please verify that you are not a robot.
The appspot demo prints the siteverify result its backend got from Google. Same script, different URL:
$ CAPTCHAAI_KEY=... node recaptcha-v2-puppeteer.mjs https://recaptcha-demo.appspot.com/recaptcha-v2-checkbox.php
00:35:28Z anchor k=6LfW6wATAAAAAHLqO2pb8bDBahxlMxNdo9g947u9 size=normal /recaptcha/enterprise/anchor
00:35:28Z anchor k=6Le80pApAAAAANg24CMbhL_U2PASCW_JUnq5jPys size=invisible /recaptcha/enterprise/anchor
00:35:28Z sitekey 6LfW6wATAAAAAHLqO2pb8bDBahxlMxNdo9g947u9 (data-sitekey: same)
00:35:28Z task 5608596705 submitted
00:36:04Z task 5608596705 solved in 36.3s
00:36:04Z token 0cAFcWeA5kTm3wIaWkKQ... (2574 chars)
00:36:05Z page says: 'success' => true, | 'hostname' => 'recaptcha-demo.appspot.com',
Look at the first anchor. Six minutes earlier the same key came from /recaptcha/api2/anchor (the Step 1 output). This time it came from /recaptcha/enterprise/anchor. Both times I sent it as a plain v2 task, and both times siteverify said success. So /enterprise/ in the path doesn't prove the key is Enterprise.
How long the solves took
Here is every task from tonight's runs on the two demos, in order: 120.8 s (a first test of this flow), 104.6 s, one still unsolved at 180 s, 130.9 s for its replacement, then 78.4, 83.5, 99.4, 99.7 (a check of the raw replies), 57.3 and 36.3 s. Nine tokens and one timeout. This is the run with the timeout:
00:24:07Z task 5608489555 submitted
00:27:10Z task 5608489555 not solved in 180s
00:27:10Z task 5608518717 submitted
00:29:21Z task 5608518717 solved in 130.9s
The page sat there for more than five minutes, and the demo still accepted the token, because the token itself was fresh. The runs for the Selenium post on 2026-10-10 took 45, 90, 91 and 114 seconds, and one of five timed out. So plan for up to two minutes, sometimes more, and keep the 180-second cap with one retry.
A token is valid for two minutes and can be verified once. Ask for it when the form is ready, submit straight away, and never reuse one.
What can still go wrong
-
waitForNavigationtimes out after the injection. The form submits with fetch, so there's no navigation to wait for. Wait for the site's success element, or for its response withpage.waitForResponse(). - The site says "please verify" even with a real token. Usually the token expired or was used already. Next, check that it went into the textarea of the form you submitted.
-
The widget really is Enterprise. The anchor path only hints at it, as the appspot runs showed. A real Enterprise key takes
enterprise=1, and the reply includes a User-Agent you have to submit with. This comparison of v2, v3 and Enterprise shows how to tell. -
The token is accepted and the site still blocks you. reCAPTCHA is often one check among several. A valid token doesn't change
navigator.webdriver(true in the click runs above) or your IP's reputation. The demos didn't care about either. Your target might.
FAQ
Do I need puppeteer-extra-plugin-recaptcha?
No. According to its README, page.solveRecaptchas() finds the widgets on the page, passes their configuration to a solving provider you configure, and puts the solutions back into the page, triggering any callback the widget needs. Apart from that callback, which this script leaves to you (Step 3), those are the steps above. Done by hand they come to about 100 lines on top of plain puppeteer, comments included, and when one fails, the log tells you which.
Can I make Puppeteer tick the checkbox itself?
Not reliably in headless Chrome. In my six runs the click opened the image challenge every time.
How long can I keep a token?
Two minutes from when it was issued, and one verification. Solve right before you submit.
Disclosure: I run CaptchaAI, the API these examples call. This article was written by an AI agent, and every output above is from a real run on 2026-10-18.
— Bassem
Top comments (0)