A QA engineer adds an E2E test for a registration form. The test reaches the CAPTCHA and fails, not because of a bug, but because the CAPTCHA blocks the automated request.
QA engineers, developers setting up CI/CD, and automation specialists testing integrations with third-party websites all run into this problem. After reading this article, you will know when a test key is enough, when you need a CAPTCHA-solving API, and how to integrate both approaches into your test scenario.
Why CAPTCHA Breaks Automated Tests#
Different types of CAPTCHA check different signals. Some analyze browser parameters and the interaction context, while others require an explicit action, such as solving a puzzle, selecting images, or entering text from an image.
Selenium and Playwright emulate some user actions, but headless mode and typical automation settings differ from a regular browser in terms of timings and environment parameters. A CAPTCHA that analyzes the interaction context can react to these differences and block the test. A CAPTCHA with an explicit challenge requires an additional step: the puzzle or images must be solved regardless of how realistically the behavior was emulated before that step.
What Options Are Available for Passing CAPTCHA in a Test#
Disabling the CAPTCHA with an environment flag or replacing it with a mock is also an option if you have access to the application's code and configuration. This article covers two approaches for cases where the CAPTCHA remains on the page as is, whether in production or test mode:
- a test key from the CAPTCHA provider, which you add to the page code instead of the production key
- a CAPTCHA-solving API, which accepts the
sitekeyand page URL and returns a ready-to-use token
Each approach fits different conditions. Below, we will look at when to use each one.
When a Test Key Solves the Problem#
A test key works if you control the page code and can replace the production key with it. This determines whether the approach is suitable for your setup.
Google reCAPTCHA v2 provides official test keys in its documentation:
- site key:
6LeIxAcTAAAAAJcZVRqyHh71UMIEGNQ_MXjiZKhI - secret key:
6LeIxAcTAAAAAGG-vFI1TnRWxMZNFuojJ4WifJWe
The keys always return a successful verification and do not check the domain. Google warns that users will see the message "This reCAPTCHA is for testing purposes only" on the page, but server-side verification will succeed.
Cloudflare Turnstile documents test sitekey values with different behaviors:
1x00000000000000000000AAalways passes verification (visible widget)2x00000000000000000000ABalways blocks verification (visible widget)3x00000000000000000000FFalways shows an interactive challenge1x00000000000000000000BBalways passes verification (invisible widget)2x00000000000000000000BBalways blocks verification (invisible widget)
hCaptcha provides the test sitekey 10000000-ffff-ffff-ffff-000000000001, which also passes verification without requiring a real solution.
When a Test Key Is Not Enough#
A test key is not suitable if you do not control the page code or environment. For example, there are two common cases:
No development environment. The product only has a production environment, and the developers have not added a flag for replacing the key with a test key. There is nowhere to add the test sitekey, and changing the production key for testing is risky because it would disable protection for real users.
The page belongs to a third party. You are testing an integration with a partner service or payment provider. You do not have access to their HTML, so you cannot replace the test key. The site owner decides which key the page uses, not you.
In both cases, the test uses the real sitekey and solves the CAPTCHA through an API instead of replacing it with a test key.
How to Solve CAPTCHA Through an API#
The process is the same whether you are testing your own site without a development environment or a third-party page:
sitekey + URL → createTask → getTaskResult → token → test
- Get the
sitekeyand the URL of the page with the CAPTCHA. - Create a task using the
createTaskmethod. - Get the token using the
getTaskResultmethod. - Pass the token to the form and continue the test scenario.
Scenario: Testing a Partner Integration#
The team does not have access to the partner service's code, and the service uses Turnstile on its login form. Replacing the production sitekey with a test key is impossible because the HTML belongs to the partner.
The test follows the same sequence described above: it gets the real sitekey, solves the CAPTCHA through an API, and passes the token to the login form. The scenario passes the CAPTCHA step and continues testing the rest of the integration.
The same approach applies when testing services that do not provide an API for automation: the CAPTCHA is solved through an external service instead of through access to page code that you do not have.
What to Do Next#
If you control the page code and have a development or staging environment, start with the CAPTCHA provider's test key. It does not require external services or spend time solving a real CAPTCHA.
If you do not have access to the page code, whether you are dealing with production without an environment flag or a third-party website, use a CAPTCHA-solving API: get the sitekey and URL, call createTask, retrieve the token through getTaskResult, and pass it to the test.
How to Connect Captcha Solver#
If you need this approach in your automated tests, Captcha Solver provides an API with the same createTask and getTaskResult methods. The API is compatible with the anti-captcha format, so existing client libraries built for this format can be connected by replacing the base URL with https://api.captcha-solver.com.
The service solves reCAPTCHA v2 (including Enterprise), reCAPTCHA v3, Cloudflare Turnstile, Yandex SmartCaptcha, GeeTest v3/v4, Tencent, as well as ImageToTextTask and CoordinatesTask for image-based CAPTCHAs without a sitekey.
To connect the service to your test:
- Sign up and confirm your email.
- Get your
clientKeyin the dashboard. - Add funds to your balance.
- Pass the
clientKey,sitekey, and page URL tocreateTaskas described above.
The service uses a pay-per-solve model. No company registration is required.
Pricing by CAPTCHA type is available on the Pricing page. Request formats and the complete list of fields for each task type are available in the API documentation.