How to Bypass CAPTCHAs With Cypress

Discover how to handle CAPTCHAs in Cypress, including effective bypass methods and what to do when CAPTCHAs persist, ensuring seamless browser automation.
8 min read
How to Bypass CAPTCHAs With Cypress blog image

In this article, you will learn:

  • What CAPTCHAs are and whether they can be bypassed
  • The relationship between Cypress and CAPTCHAs
  • How to implement Cypress CAPTCHA bypass logic
  • What to do in case the CAPTCHA still shows up

Let’s dive in!

What Is a CAPTCHA and Is It Possible To Automate It?

A CAPTCHA, which stands for “Completely Automated Public Turing tests to tell Computers and Humans Apart,” is a method used to differentiate real users from automated bots. It is a challenge designed to be straightforward for humans to solve but challenging for machines. Usually, CAPTCHAs are used in specific parts of a web page to keep bots away.

Google reCAPTCHA, hCaptcha, and BotDetect are the most popular CAPTCHA providers. These support one or more of the following challenges:

  • Text-based CAPTCHAs: Users are required to type a sequence of distorted letters and/or numbers.
  • Image-based CAPTCHAs: Users need to identify specific objects in a grid of images.
  • Audio-based CAPTCHAs: Users are asked to type the words they hear.
  • Puzzle CAPTCHAs: Users must answer a simple question or solve a simple mini-game, such as clicking on the right entity.
Puzzle CAPTCHA example

CAPTCHAs can be integrated into specific user flows to prevent bots from completing it, such as submitting a form:

captcha as a step of a form submission process example

In these cases, the CAPTCHA is always displayed and cannot easily be bypassed by automated logic. You can integrate your software with CAPTCHA-solving libraries or utilize services that rely on human operators to solve these challenges in real-time. However, hard-coded CAPTCHAs are uncommon because they are annoying and degrade the user experience.

More commonly, CAPTCHAs are part of more advanced anti-bot solutions, such as WAFs (Web Application Firewalls):


These solutions dynamically display a CAPTCHA when they suspect the current user may be a bot. In such cases, CAPTCHAs can be avoided by making your bot behave like a human and utilize a real-world browser. Nevertheless, this is an ongoing battle that requires continually updating your automated script to deal with always-evolving bot detection measures.

A more effective solution for evading CAPTCHAs is to use a user-emulation-based tool that is always up-to-date, such as Bright Data’s CAPTCHA Solver.

CAPTCHAs and Cypress: A Bad Relationship

Cypress is a front-end testing tool built for the modern Web. While it can be used for general browser automation tasks, such as web scraping, its main focus is end-to-end(E2E) testing. That means it is designed to interact primarily with sites and web pages that you have control over.

Use Cypress to target external or third-party sites and problems start to arise. As highlighted in the official documentation, the best practice is to avoid interacting with third-party sites as much as possible. One of the main reasons highlighted in the docs is specifically the risk of being detected as a bot and getting a CAPTCHA.

Why is this a problem? Well, because CAPTCHAs are designed to stop automated scripts. Thus, they can hinder your Cypress browser automation operation. At the same time, it is important to note that bypassing CAPTCHAs in Cypress is tricky but possible. Find out more in the next sections!

How to Handle CATPCHAs in Cypress

As you just learned, CAPTCHAs are one of Cypress’s main challenges, as recognized by the tool itself in its documentation. However, it is not time to raise the white flag just yet. Let’s explore some potential approaches for implementing Cypress CAPTCHA bypassing logic!

Approach #1: Disable the CAPTCHAs

CAPTCHA providers generally offer a way to disable or skip challenges in a testing environment. If you have control over the site where you need to perform automation on, you should then disable the CAPTCHA mechanism altogether or replace it with a simpler version.

For example, with reCAPTCHA v3, you can create a separate key for testing environments. For reCAPTCHA v2, you can use the following test keys:

  • Site key: 6LeIxAcTAAAAAJcZVRqyHh71UMIEGNQ_MXjiZKhI
  • Secret key: 6LeIxAcTAAAAAGG-vFI1TnRWxMZNFuojJ4WifJWe

While using these keys, you will always get a reCAPTCHA “No CAPTCHA” widget as below:

This will show a special warning message to ensure it is not used in production. Automate the click on that check and the anti-bot verification will always pass. Find out more in the reCAPTCHA documentation.

Note that other CAPTCHA providers offer similar mechanisms.

Approach #2: Automate the CAPTCHA Interaction

Some CAPTCHAs only require simple actions—like clicking a checkbox—as in the reCAPTCHA “No CAPTCHA” widget:

Simple clicking CAPTCHA example

These challenges may seem straightforward but can actually be sophisticated, analyzing your mouse movements to determine if you are human. Still, not all CAPTCHAs are this complex. Some are designed to stop basic bots and are simpler to bypass. In such cases, you can try to automate them using some Cypress logic.

If you inspect the CAPTCHA element from the example above, you will see that it is an iframe:

Inspecting the CAPTCHA element

This is a common behavior for most CAPTCHA providers.

Keep in mind that Cypress cannot automatically deal with cross-domain iframes. To overcome that limitation, set the chromeWebSecurity property to false in the cypress.json file:


"chromeWebSecurity": false


You can then select the CAPTCHA checkbox element and click it. In case of a reCAPTCHA “No CAPTCHA” widget, the automation code for doing that will be:



.should(d => d.getElementById('recaptcha-token').click())

Remember, this is just a workaround and will not work in most situations. CAPTCHAs have become sophisticated enough to distinguish between clicks from a robot and a human. At the end of the day, that is exactly what a CAPTCHA is all about.

Automating CAPTCHAs is a cat-and-mouse game, and what works today may not work tomorrow. For the most up-to-date approaches, check out the GitHub gist where this approach comes from.

Approach #3: Integrate an Antibot Browser

The previous two Cypress CAPTCHA bypass approaches require too many assumptions to be used against a real target. A more effective solution is to configure Cypress to control an anti-detect browser. If you are unfamiliar with that tool, an anti-detect browser is a specialized browser designed to prevent websites from detecting automated behavior.

By default, Cypress provides access to one of the locally installed browsers from the following list:

  • Chrome
  • Chrome Beta
  • Chrome Canary
  • Chromium
  • Edge
  • Edge Beta
  • Edge Canary
  • Edge Dev
  • Electron
  • Firefox
  • Firefox Developer Edition
  • Firefox Nightly
  • WebKit (Experimental)

On top of those, it supports any Chromium-based browsers. So, choose a Chromium-based browser from the list of the best anti-detect browsers on the market, buy it, download it, and install it on your machine.

You can then instruct Cypress to launch a script with the specified browser as below:

cypress open --browser <path_to_your_browser>

Where <path_to_your_browser> is the absolute path to the folder containing the binary of your anti-detect browser.

Similarly, you can configure the Cypress UI to show your anti-detect browser as a selectable option by adding the following code in cypress.config.js:

import { defineConfig } from 'cypress'

export default defineConfig({

e2e: {

setupNodeEvents(on, config) {

const antidetectBrowser = {


channel: 'stable',

family: 'chromium',



path: '<path_to_your_browser>',



return {

browsers: config.browsers.concat(antidetectBrowser),





Note that instructing Cypress to run your automated code in an anti-detect browser will only reduce the chance of getting detected as a bot. If the anti-bot systems understand that you are running automated code, they may still enforce some CAPTCHAs to stop you.

The Cypress CAPTCHA Bypass Solutions Above Do Not Work: What to Do Now?

All three methods presented above have some major drawbacks:

  • Approach #1: It requires you to have access to the code of the target site, which is not the case when dealing with external online sites.
  • Approach #2: It works only against very simple CAPTCHAs and is not a reliable technique.
  • Approach #3: It requires you to buy an external service, you may have to spend additional money for proxy integration, and it only helps avoid CAPTCHAs, not solve them.

While they are all worth trying, none of them allow you to bypass CAPTCHAs programmatically in your Cypress automation.

Looking for a real Cypress CAPTCHA bypasser? Try Bright Data web scraping solutions!

These offer superior unlocking capabilities thanks to a dedicated CAPTCHA-solving feature to automatically handle reCAPTCHA, hCaptcha, px_captcha, SimpleCaptcha, GeeTest CAPTCHA, FunCaptcha, Cloudflare Turnstile, AWS WAF Captcha, KeyCAPTCHA, and many others.

Integrating Bright Data’s CAPTCHA Solver into your script is simple, as it works with any HTTP client or browser automation tool—including Cypress.

Learn more about how to use Bright Data’s Web Unlocker. Also, check out the documentation for all integration and configuration details.


In this article, you learned about CAPTCHAs and why they pose a significant challenge for Cypress. You also explored three different methods to bypass them, but each of these approaches has serious limitations.

No matter how advanced your Cypress bypass CAPTCHA logic is, sophisticated bot detection systems might still identify your script as automated. The best solution is to connect to your target site through an unlocking API that can return the CAPTCHA-free HTML of any web page.

Such an API exists and is called Web Unlocker. This automatically rotates the exit IP with each request via proxy integration, handles browser fingerprinting, performs automatic retries, and resolves CAPTCHAs for you. Anti-bot measures are no longer a headache!

Register now and see which of Bright Data’s products best suits your needs. Start with a free trial today.

No credit card required