Cloudflare Turnstile with Selenium is easiest when you treat CAPTCHA solving as a controlled integration, not a last-minute patch.
The reliable pattern is always the same: detect the challenge, capture the right parameters, send a clean task to the solver, inject the token at the correct point, and verify the protected action server-side.
Prerequisites
Before writing solver code, confirm the challenge type and parameters. For Cloudflare Turnstile, the minimum useful record is page URL, sitekey or challenge key, action/callback name if present, user agent, proxy label, and the exact submit endpoint that consumes the token.
Keep these values in logs for every attempt. Most integration failures come from stale page snapshots, wrong sitekeys, missing callback execution, or tokens submitted after their freshness window expired.
Detection step
Do not assume the challenge appears on every request. A robust script first checks whether the real application page loaded, whether a challenge widget exists, or whether the request was blocked by policy.
async function detectCaptcha(page) {
const turnstile = await page.$('iframe[src*="challenges.cloudflare.com"]');
const hcaptcha = await page.$('iframe[src*="hcaptcha.com"]');
const recaptcha = await page.$('[name="g-recaptcha-response"], iframe[src*="recaptcha"]');
if (turnstile) return 'turnstile';
if (hcaptcha) return 'hcaptcha';
if (recaptcha) return 'recaptcha';
return 'none';
}
The selector list should be customized to your site. Treat it as a guardrail, not a universal detector.
Solver request
The solver request should include only the fields the provider needs, but it must include the fields that bind the token to the right session. For Cloudflare Turnstile, that usually means the current page URL, current sitekey, user agent, and proxy when the target binds risk to network reputation.
Use short timeouts. A token that arrives after the form session changes is not useful. A good default is 60 seconds for visible challenges, 90 seconds for FunCAPTCHA, and a hard retry limit of one fresh token after timeout.
Token injection
Token injection depends on the integration. Some pages read a hidden textarea. Others register a callback. Others submit through an XHR body. Inspect the page you control and inject at the same boundary the real widget uses.
await page.evaluate((token) => {
const field = document.querySelector('[name="g-recaptcha-response"], [name="h-captcha-response"], [name="cf-turnstile-response"]');
if (field) {
field.value = token;
field.dispatchEvent(new Event('input', { bubbles: true }));
field.dispatchEvent(new Event('change', { bubbles: true }));
}
}, solverToken);
If the site uses a callback, call the callback with the token instead of only writing the hidden field.
Verification and fallback
A returned token is not success. The only success metric that matters is whether the protected action accepted it. Record the submit response, redirect target, and any server-side validation error.
If one provider fails, request a fresh token from a fallback provider. Do not reuse the failed token, and do not retry indefinitely. Two total attempts is usually the right ceiling for production automation; more attempts often indicate a broken sitekey, missing parameter, or Cloudflare/WAF policy block.
Production QA checklist
Before you rely on Cloudflare Turnstile with Selenium in production, test it like an operational dependency rather than a code snippet. Run a small controlled sample, record every solver task ID, and compare returned-token rate with accepted-submit rate. Those two numbers should never be treated as the same metric: a provider can return a token quickly while the protected action still rejects it because the token is stale, the callback was not executed, the wrong page URL was used, or the browser session changed after the challenge loaded.
A useful QA pass includes one clean manual baseline, one automated run without a solver where possible, and one automated run with the selected provider. Capture screenshots and HTML snapshots for failures. Keep provider credentials, proxy labels, and environment names out of screenshots, but preserve enough context that another engineer can reproduce the failure without guessing.
Metrics to track after launch
The operational dashboard should track p50 and p95 solve time, task creation errors, timeout rate, unsolvable rate, accepted-submit rate, token age at submit, and cost per accepted action. Cost per accepted action is the number that matters most for business planning: provider spend divided by successful protected actions, not provider spend divided by returned tokens.
Review these metrics by CAPTCHA type and by provider. Mixed averages hide the exact regressions that hurt teams in production. A provider may be excellent on reCAPTCHA v2 and weak on Turnstile, or stable on normal weekday traffic and unreliable during high-volume launches. When p95 or accepted-submit rate changes suddenly, freeze provider routing, inspect recent site changes, and compare against CaptchaRank live benchmark data before assuming the code broke.
FAQ
Can I reuse CAPTCHA tokens?
No. Treat tokens as single-use and short-lived. Reusing tokens creates invalid-token failures that look like provider problems but are actually integration bugs.
Should I use the same proxy for page load and solver?
When the target binds risk to network/session signals, yes. Use the same egress label or proxy family whenever the provider supports proxy-based solving.
What is the most common integration bug?
Submitting a token to the wrong field or missing the page callback. Always inspect the target integration and mirror how the real widget passes the token.
How do I know the provider is the issue?
Compare returned-token rate to accepted-submit rate. If tokens return but submissions fail, inspect sitekey, callback, token age, and proxy before blaming the provider.
Compare live CAPTCHA solver performance on CaptchaRank — visit captcharank.com/solvers for the live leaderboard or captcharank.com/compare for head-to-head provider comparisons.
