Skip to main content

Solving CAPTCHAs

CAPTCHAs are a common roadblock in automation. BrowserQL includes built-in support for CAPTCHA challenges. BQL will automatically detect and interacts with CAPTCHAs, even those embedded in iframes or shadow DOMs. You can use the following mutations:

Verify​

The Verify mutation clicks a verification button to assert human-like interaction. This mutation can be used to surpass cloudflare's human verification step.

If you're not sure whether a site has Cloudflare protection, you can use the if mutation with a waitForSelector to conditionally run the verification. Since the if mutation doesn't wait for a selector to be present, adding a waitForSelector before it ensures the Cloudflare turnstile is available before attempting verification.

    mutation Verify {
      goto(url: "https://protected.domain") {
        status
      }

      verify(type: cloudflare) {
        found
        solved
        time
      }
    }

Conditional Cloudflare Verification​

Here's an example of using conditional verification with the if mutation:

    goto(url: "https://www.browserless.io/practice-form") {
      status
    }
    waitForSelector(selector:".cf-turnstile",timeout:1000){
      time
    }
    if(selector:".cf-turnstile"){
      verify(type:cloudflare,timeout:30000){
        found
        solved
        time
      }
    }
    html{
      html
    }

Note that .cf-turnstile is specific to our sample website. For your own implementation, you should look for a selector that works for your target website. Some alternatives that might work on other sites include a[href*="cloudflare.com"] or other Cloudflare-specific elements.

Solve​

The Solve mutation solves a captcha, specified by the "type" of captcha to solve. Currently, BQL can solve turnstile reCAPTCHAs and hCAPTCHAs only. Image-based CAPTCHAs are not supported yet.

info

When solving reCAPTCHAs, it's normal if there isn't a visual confirmation that the CAPTCHA has been solved (i.e., the checkbox may not appear ticked). This is expected behavior. After solving, you should proceed and click on the form's submit button.

mutation SolveCaptcha {
  goto(url: "https://protected.domain") {
    status
  }

  solve(type: hcaptcha) {
    found
    solved
    time
  }
}

Form Submission After Solving​

After solving a CAPTCHA, you should proceed with form submission by clicking the submit button:

mutation SolveAndSubmit {
  goto(url: "https://protected.domain") {
    status
  }

  solve(type: recaptcha) {
    found
    solved
    time
  }
  
  click(selector: "button[type='submit']") {
    time
  }
}

If there isn't a submit button available, you can trigger form submission manually using the evaluate mutation:

mutation SolveAndTriggerSubmit {
  goto(url: "https://protected.domain") {
    status
  }

  solve(type: recaptcha) {
    found
    solved
    time
  }
  
  evaluate(content: "window.onSubmit()") {
    time
  }
}

Replace window.onSubmit() with the appropriate JavaScript function that submits the form on your target website.