A captcha on your signup form exists to stop automated browsers. Your end-to-end test suite is an automated browser. So the moment you add reCAPTCHA, hCaptcha or Turnstile to signup, some tests start failing, or worse, start passing for the wrong reason.
The fix isn't one trick. It's deciding what each layer of your test suite is responsible for, and giving each layer the captcha setup that matches. This post walks through four layers, from unit tests to production, with the gotchas that tend to show up at each one.
Everything here is about testing forms on sites you own or are authorized to test.
Layer 1: unit tests never call the provider
Your backend's job is small: take the token from the form, send it to the provider's siteverify endpoint with your secret, and decide. That decision logic is where most real bugs live, and it doesn't need a network call to test.
Put verification behind an interface so tests can swap in a fake:
// captcha.ts export type Verdict = { ok: true } | { ok: false; reason: string }; export interface CaptchaVerifier { verify(token: string | undefined, remoteIp?: string): Promise<Verdict>; } type SiteverifyResponse = { success: boolean; hostname?: string; "error-codes"?: string[]; }; export function httpVerifier(opts: { url: string; // e.g. https://www.google.com/recaptcha/api/siteverify secret: string; expectedHostname?: string; // per environment, see below timeoutMs?: number; }): CaptchaVerifier { return { async verify(token, remoteIp) { if (!token) return { ok: false, reason: "missing-token" }; const body = new URLSearchParams({ secret: opts.secret, response: token }); if (remoteIp) body.set("remoteip", remoteIp); try { const res = await fetch(opts.url, { method: "POST", body, signal: AbortSignal.timeout(opts.timeoutMs ?? 5000), }); const data = (await res.json()) as SiteverifyResponse; if (!data.success) { return { ok: false, reason: (data["error-codes"] ?? ["unknown"]).join(",") }; } if (opts.expectedHostname && data.hostname !== opts.expectedHostname) { return { ok: false, reason: "hostname-mismatch" }; } return { ok: true }; } catch { // Provider down or slow: fail closed, and make it visible in logs. return { ok: false, reason: "verify-unavailable" }; } }, }; } Your signup handler takes a CaptchaVerifier as a dependency. In unit tests you pass a fake that returns whatever verdict the test needs. The cases worth a test each:
- No token in the request at all (a bot posting straight to your endpoint).
-
timeout-or-duplicate. Google's verify docs say a reCAPTCHA token is valid for two minutes and can be verified only once. A user who leaves the form open, or a double-submit, hits this. Does your UI ask them to retry, or show a generic 500? -
invalid-input-secret. That's a config error, not a user error. Alert on it instead of telling the user they look like a bot. - Hostname mismatch.
- The provider timing out. Decide on purpose whether signup fails closed or open, and test that decision.
None of these need a browser or a real key.
Layer 2: local and CI end-to-end tests use the vendor's test keys
For browser tests, each provider publishes keys that always pass (and, for some, keys that always fail). Use them in local development and CI:
- reCAPTCHA v2: Google's FAQ lists a site key and secret key pair that always passes with no challenge. The widget shows a warning so it doesn't end up serving production traffic by accident.
- hCaptcha: a test sitekey, a zero-filled test secret and a fixed response token. The docs warn that test keys give no bot protection at all.
- Turnstile: sitekeys that pass, fail, run invisibly or force an interactive challenge, plus secret keys that pass, fail or report a spent token. Turnstile in Playwright gets a full walkthrough in an earlier post on test keys versus real keys.
Copy the exact values from the vendor docs rather than from a blog post (this one included). A single wrong character gives you an "invalid key" error that looks like a network problem.
Three things trip people up here.
Swap both halves. A test sitekey produces a dummy token that your production secret will reject. hCaptcha even has a specific error code for this, not-using-dummy-passcode. If you change only the frontend key, the form "works" until the server says no.
Test secrets don't return your hostname. Cloudflare's testing page says a successful response from a test secret always reports example.com as the hostname. If your verifier checks the hostname (it should), that check fails in CI. That's why expectedHostname in the code above is a per-environment setting: leave it unset with test keys, and set it everywhere real keys run.
reCAPTCHA v3 has no universal test key. Google's FAQ says to create a separate key for test environments and warns that scores may not be accurate, because v3 depends on seeing real traffic. On the Google Cloud side, you can create testing keys with gcloud recaptcha keys create and the --testing-score flag, which pins the score to a value you choose. You can't convert those keys later or edit them, only delete them, so name them clearly.
Localhost needs care too. Google says localhost isn't on a key's domain list by default and recommends allowing it only on your development key. hCaptcha's API doesn't accept localhost or 127.0.0.1 as a hostname and suggests a hosts-file entry instead.
The "skip captcha" flag needs a guard
Plenty of teams add a CAPTCHA_DISABLED=true switch instead of using test keys. That's fine for a dev laptop, but it's exactly the setting that leaks into production through a copied .env file. If you have one, make the app refuse to start with it in production:
// config-guard.ts — run at startup const TEST_SITEKEYS = new Set<string>([ // paste the vendor test sitekeys you use, from their docs ]); export function assertCaptchaConfig(env: NodeJS.ProcessEnv) { if (env.APP_ENV !== "production") return; if (env.CAPTCHA_DISABLED === "true") { throw new Error("CAPTCHA_DISABLED is set in production"); } if (!env.CAPTCHA_SITEKEY || TEST_SITEKEYS.has(env.CAPTCHA_SITEKEY)) { throw new Error("Production is using a missing or test captcha sitekey"); } if (!env.CAPTCHA_EXPECTED_HOSTNAME) { throw new Error("Set CAPTCHA_EXPECTED_HOSTNAME in production"); } } A crash on deploy is much cheaper than a week of bot signups nobody noticed.
Layer 3: staging runs real keys, on purpose
Test keys prove your plumbing works. They can't prove your real configuration works, and that's where launch-day bugs come from:
- The production domain is missing from the key's domain list. Google's key docs say list changes can take up to 30 minutes to apply, so a last-minute fix isn't instant.
- A Content Security Policy blocks the provider's script or iframe.
- The real secret in your secrets manager belongs to a different key than the sitekey in your frontend build.
- Hostname checks behave differently behind your CDN or a preview-deploy URL.
Google recommends separate keys for staging and production, partly so test traffic doesn't distort risk analysis on the production key. Give staging its own real key, with domain verification on, and run a small set of signup tests against it before each release.
Here you have a choice. Real keys mean real challenges, and an automated browser will often get one. You can:
- Keep the real-key suite tiny and run it by hand as a release checklist item.
- Use a score-pinned testing key (reCAPTCHA Enterprise) where your provider offers one.
- Use a captcha solving API for those few tests, so the browser gets a genuine token for your own staging site and the whole path runs unattended: real script, real widget, real siteverify, your real hostname check.
Option 3 costs money per solve and adds an outside dependency, so keep it to the handful of tests that really need real keys. It's the only one of the three that exercises the full production path without a person in the loop.
Layer 4: production gets monitoring, not a test suite
In production, the most useful signal comes from your own backend logs, not from more browser tests. Log the reason from every failed verification and graph it. A spike in invalid-input-secret means someone rotated a key. A spike in hostname-mismatch usually means a new domain or proxy. A rise in missing-token is often bots posting directly, which means the captcha is doing its job.
If you also want a synthetic signup check, run it rarely, against a dedicated test account, and clean up whatever it creates.
Checklist
- [ ] Verification sits behind an interface, and unit tests cover missing, expired/duplicate, bad secret, hostname mismatch and timeout.
- [ ] CI uses the vendor test sitekey and matching test secret.
- [ ] The hostname check is configured per environment and turned on wherever real keys run.
- [ ] v3: a separate test key, or a score-pinned testing key.
- [ ] Localhost is allowed only on the development key.
- [ ] Startup refuses production with a disable flag, a test sitekey or no expected hostname.
- [ ] Staging has its own real key and a small real-key suite before each release.
- [ ] Production logs failure reasons and alerts on config-type errors.
Where CaptchaNo fits
Disclosure: I work on CaptchaNo, a captcha solving API. It fits layer 3: running a few real-key signup tests on your own staging site without someone clicking through challenges.
You send one POST /v1/solve with the captcha type, your page URL and the sitekey. With ?wait=60 the call holds until the solve finishes and returns the token. If the solve outlasts that window, you poll GET /v1/task/{id}. The request and response format is documented, and there's a ready-made Playwright integration example. Supported types are reCAPTCHA v2, v3 and Enterprise, Cloudflare Turnstile, DataDome and image/text captchas. We don't support hCaptcha, so for hCaptcha forms, stick with its test keys.
Solves run on our own solving infrastructure. If you're wiring it into a test harness and something doesn't behave as expected, the engineers who run the service answer at support@captchano.com. Billing is per successful solve: failed solves aren't charged, and credit doesn't expire. The current per-type rates are on the pricing page.
Use it only on sites you own or are authorized to test, and for permitted automation.



