Testing Pages with a CAPTCHA

A CAPTCHA exists to stop automation, so a test that has to get past a real one is fighting its own application. The three big vendors publish test keys for this: with them the widget gives a known answer and the vendor’s server accepts (or refuses) the result on purpose. You run the application under test with those keys, and the browser test clicks the test widget, checks that the token field was filled, and submits.

How the pieces fit#

1. Your page embeds the vendor’s widget with a site key.
2. When the widget is satisfied it writes a token into a hidden field of your form.
3. Your server sends the token and its secret key to the vendor’s verification endpoint (siteverify) and acts on the answer.

Who talks to whom.

With the vendor’s test keys, step 1 hands out a token without a real risk check and step 3 accepts it (or refuses it, for the keys made to fail). Only the keys differ from production, so the code under test is the code you ship.

Configure the app under test#

Keep the keys in the environment, as for any other deploy-specific setting, and set the test keys only in the test deployment:

# .env.test: the test deployment only, never productionCAPTCHA_SITE_KEY=6LeIxAcTAAAAAJcZVRqyHh71UMIEGNQ_MXjiZKhICAPTCHA_SECRET_KEY=6LeIxAcTAAAAAGG-vFI1TnRWxMZNFuojJ4WifJWe

• Use a site key and secret of the same set. Cloudflare’s test secrets accept only the dummy token and production secrets reject it, so a dummy site key next to a real secret fails.
• Make the siteverify URL a setting too. Then a test can point the server at a stub, which is the way to cover reCAPTCHA v3 and any answer a test key cannot give. The same setting can switch the check off: pointed at a stub, or at any server that always answers success: true, it makes your server accept every token. Outside the test deployment, have the application refuse to start unless the URL is the vendor’s own siteverify URL (listed below); production keys are real, so the test-key check in the next point does not catch a wrong URL.
• Test keys protect nothing, and the secrets are public. Have the application refuse to start with a known test key when it runs in production.

The test keys#

Every value below was compared character by character with the vendor’s page on 2026-10-15 and each page can change, so check it again before you rely on it.

What siteverify answered#

These calls were made on 2026-10-15 with the keys above, to check that the secrets behave as documented:

Your own server tests can use the same pairs: they cover its handling of a rejected and of an already-used token without opening a browser.

Click the widget and read the token#

The test has the same four steps for every vendor:

The first two widget selectors are the ones Page::solve_captcha itself uses.

To try the code without your own application, save this HTML as recaptcha.html and serve its folder (python3 -m http.server 8765 --bind 127.0.0.1). For hCaptcha or Turnstile swap the script, the div and the site key, and save each as a file of its own (hcaptcha.html, turnstile.html): one vendor per page. Its form has no server behind it, so the token is what a test can check:

<!doctype html><html lang="en"><head><meta charset="utf-8"><title>reCAPTCHA v2 test fixture</title><script src="https://www.google.com/recaptcha/api.js" async defer></script></head><body><form id="signup" action="/verify" method="post">  <input type="text" name="email" id="email">  <div class="g-recaptcha" data-sitekey="6LeIxAcTAAAAAJcZVRqyHh71UMIEGNQ_MXjiZKhI"></div>  <button type="submit" id="send">Send</button></form></body></html>

What solve_captcha does#

Page::solve_captcha() (and BaseCase::solve_captcha(), which does the same over chromedriver) looks for the first visible widget among Cloudflare Turnstile, reCAPTCHA, hCaptcha, Friendly Captcha and DataDome, in that order, scrolls it to the middle of the window, and presses 28 pixels in from its left edge at half its height with trusted mouse events (the DataDome slider is pressed 30 pixels in and dragged to 30 pixels from the right edge). The widgets live in cross-origin frames whose insides it cannot inspect, so it does not know whether the click was accepted. It returns Some(Captcha::...) for the widget it pressed, None when no supported widget is visible yet, and an error when the script that looks for the widget fails or the browser refuses the input. The script can fail while the page is still navigating (“Execution context was destroyed”), so such an error need not end a test that has just submitted a form or followed a link: wait for the page to load and call it again. Because None is what you get before the widget has drawn, wait for the widget first, and check the token afterwards.

With the gui feature, Page::gui_click_captcha() makes the same press with the machine’s own pointer; test widgets do not need it (see Pure CDP).

With the pure CDP engine#

use std::time::Duration;use seleniumbase_rs::sb_cdp::{Browser, Captcha, LaunchOptions, Page, State};use seleniumbase_rs::SeleniumBaseError;/// Presses `widget` until the hidden field `field` holds a token, and returns/// the token.////// The widget's frame can be on screen before the checkbox inside it has/// drawn, and a press that early is lost. `solve_captcha` cannot tell, so each/// press gets five seconds to produce a token, and the widget is pressed again/// if none came.async fn press_until_token(    page: &Page,    widget: Captcha,    field: &str,) -> Result<String, SeleniumBaseError> {    // Truthy once the field holds a token; the `?.` keeps it from throwing    // before the field exists.    let token = format!("document.querySelector('{field}')?.value");    let short = page.with_timeout(Duration::from_secs(5));    for _ in 0..3 {        assert_eq!(page.solve_captcha().await?, Some(widget));        match short.wait_for_function(&token).await {            Ok(()) => return page.evaluate_as(&token).await,            // No token: the press came too early, so press again.            Err(SeleniumBaseError::WaitTimeout(_)) => {}            Err(other) => return Err(other),        }    }    Err(SeleniumBaseError::WaitTimeout(format!(        "no token in {field} after three presses"    )))}#[tokio::test]async fn signup_with_the_recaptcha_test_widget() -> Result<(), SeleniumBaseError> {    let browser = Browser::launch(LaunchOptions::builder().headless(true).build()?).await?;    let page = browser.default_page().await?;    page.goto("http://localhost:3000/signup").await?;    page.locator("#email").fill("ada@example.com").await?;    // 1. Wait for the widget's frame (it is an element of your page).    page.locator(r#"iframe[src*="recaptcha/api2/anchor"]"#)        .wait_for(State::Visible)        .await?;    // 2 and 3. Click it until the token lands in the hidden field of your page.    let field = r#"textarea[name="g-recaptcha-response"]"#;    let token = press_until_token(&page, Captcha::Recaptcha, field).await?;    assert!(!token.is_empty());    // 4. Submit and assert what your application shows.    page.locator("#send").click().await?;    page.locator("body")        .expect()        .to_contain_text("Thanks")        .await?;    browser.close().await?;    Ok(())}

The same shape works for the other two vendors, with their frame and field from the table. Give each vendor a page of its own: solve_captcha presses the first widget it finds, and it looks for Turnstile before reCAPTCHA and hCaptcha, so on a page with Turnstile and hCaptcha it would press Turnstile even when the test meant hCaptcha. A test key gives a known token, so the test can assert it:

# use seleniumbase_rs::sb_cdp::{Captcha, Page, State};# use seleniumbase_rs::SeleniumBaseError;# // `press_until_token` is the helper from the listing above.# async fn press_until_token(_: &Page, _: Captcha, _: &str) -> Result<String, SeleniumBaseError> {#     unimplemented!()# }# async fn demo(page: Page) -> Result<(), SeleniumBaseError> {// hCaptcha, Publisher or Pro test key, on the hCaptcha fixture.page.goto("http://127.0.0.1:8765/hcaptcha.html").await?;page.locator(r#"iframe[src*="hcaptcha.com"][src*="checkbox"]"#)    .wait_for(State::Visible)    .await?;let field = r#"textarea[name="h-captcha-response"]"#;let token = press_until_token(&page, Captcha::Hcaptcha, field).await?;assert_eq!(token, "10000000-aaaa-bbbb-cccc-000000000001");// Turnstile, the key that forces an interactive challenge (3x...FF), on a page// of its own. Wait for the container to be visible, not only to exist: the// empty div has no height until the widget starts to draw (unless your CSS// gives it one), and solve_captcha skips a widget without a size.page.goto("http://127.0.0.1:8765/turnstile.html").await?;page.locator(".cf-turnstile").wait_for(State::Visible).await?;let field = r#"input[name="cf-turnstile-response"]"#;let token = press_until_token(&page, Captcha::Turnstile, field).await?;assert_eq!(token, "XXXX.DUMMY.TOKEN.XXXX");# Ok(())# }

A Turnstile key that always passes (1x...AA, 1x...BB) needs no click: skip press_until_token and wait for the token field with wait_for_function.

With WebDriver (BaseCase)#

BaseCase has no wait for a field’s value, so a small helper does it. The field is hidden, and get_value reads the live value property of an element whether or not it is visible:

use seleniumbase_rs::{run_browser_test, BaseCase, BrowserConfig, Result, SeleniumBaseError};/// Waits up to `seconds` for the hidden field `css` to hold a token.async fn wait_for_token(sb: &mut BaseCase, css: &str, seconds: u32) -> Result<String> {    for _ in 0..seconds * 4 {        if let Ok(value) = sb.get_value(css).await {            if !value.is_empty() {                return Ok(value);            }        }        sb.sleep(0.25).await;    }    Err(SeleniumBaseError::WaitTimeout(format!(        "no token in {css} after {seconds} seconds"    )))}#[tokio::test]async fn signup_with_the_recaptcha_test_widget() -> Result<()> {    run_browser_test(BrowserConfig::default(), async |sb| {        sb.open("http://localhost:3000/signup").await?;        sb.type_text("#email", "ada@example.com").await?;        // 1. Wait for the widget's frame.        let frame = r#"iframe[src*="recaptcha/api2/anchor"]"#;        sb.wait_for_element_visible(frame, 15).await?;        // 2. Click it: enter the frame (WebDriver can enter a frame from        //    another origin), click the checkbox, and come back out.        sb.switch_to_frame(frame).await?;        sb.click("#recaptcha-anchor").await?;        sb.switch_to_default_content().await?;        // 3. Read the token from your page.        let field = r#"textarea[name="g-recaptcha-response"]"#;        let token = wait_for_token(sb, field, 15).await?;        assert!(!token.is_empty());        // 4. Submit and assert.        sb.click("#send").await?;        sb.assert_text_visible("Thanks", "body").await    })    .await}

Google does not document the markup inside its frame. #recaptcha-anchor is the checkbox’s id as test suites have long used it, but it was not checked here, so look at it in DevTools before you depend on it. To avoid depending on it at all, replace step 2 with solve_captcha, which presses by position and never enters the frame:

# use seleniumbase_rs::sb_cdp::Captcha;# use seleniumbase_rs::{BaseCase, SeleniumBaseError};# async fn demo(sb: &mut BaseCase) -> Result<(), SeleniumBaseError> {// From the top-level document, after the widget has drawn. Chromium only.assert_eq!(sb.solve_captcha().await?, Some(Captcha::Recaptcha));# Ok(())# }

As in the pure CDP helper above, a press can come before the checkbox has drawn and be lost: give wait_for_token a few seconds, and press again when it times out.

For hCaptcha and Turnstile use solve_captcha too: Turnstile has no frame to enter, and hCaptcha’s inner markup was not checked here.

Failure paths#

A test key that fails is how you cover your error handling without a flaky real challenge:

• No token. With Turnstile 2x00000000000000000000AB the widget never produces a token. Assert that your form refuses to submit, or that your server rejects the empty token and shows your error message.
• Rejected token. Send the dummy token to siteverify with the secret 2x0000000000000000000000000000000AA (answer invalid-input-response), or with 3x0000000000000000000000000000000AA (answer timeout-or-duplicate), to test how your server reports a refused and a used token.
• Bot detected. hCaptcha’s Enterprise “bot detected” pair stands for a detected bot, for accounts that have Enterprise (it was not run here).
• reCAPTCHA documents no failing key. Stub siteverify (see above) to make the answer fail.

In CI#

• The widgets load their scripts and frames from the vendors’ hosts. A runner without network access to them, or a Content Security Policy (CSP) on your page that blocks them, shows no widget, and solve_captcha returns None. Take the hosts from each vendor’s CSP guidance (below, as read on 2026-10-15), not from a list of what one page load fetched: reCAPTCHA’s api.js adds a second script from www.gstatic.com to your page, and hCaptcha’s asset subdomains change over time and by region.

  Vendor	script-src	frame-src	Other directives
  reCAPTCHA (FAQ, the CSP question)	https://www.google.com/recaptcha/, https://www.gstatic.com/recaptcha/	https://www.google.com/recaptcha/, https://recaptcha.google.com/recaptcha/	connect-src: https://www.google.com/recaptcha/
  hCaptcha (CSP settings)	https://hcaptcha.com, https://*.hcaptcha.com	the same	style-src and connect-src: the same
  Turnstile (Content Security Policy)	https://challenges.cloudflare.com	the same	none

  Google and Cloudflare prefer a nonce on the api.js script tag to a host list; the widget passes the nonce on to the scripts it adds. A CI runner that limits outbound traffic needs the same hosts.

• Treat a token as single-use: Turnstile documents that one works once and expires after 300 seconds. Start every test from a fresh page load instead of reusing a token.

• Run Chrome headless in CI. The three widgets were clicked successfully by solve_captcha in a headless Chrome (see “What has been checked”).

Troubleshooting#

Security notes#

What has been checked#

See also#