A TestCafe captcha step is shorter than it is in most frameworks, because TestCafe test code already runs in Node. You call the solver straight from the test file, then write the token into the page with a ClientFunction. There is one thing to check before any of that, though, and getting it wrong wastes an afternoon: whether your run is using native automation or the old URL rewriting proxy. On the proxy, reCAPTCHA is broken before a solver is anywhere near it.<\/p>\n
# npm install capskip\nnpm install --save-dev testcafe\nnpm install capskip<\/pre>\n<\/div>\nCheck first: native automation or the proxy?<\/h2>\n
TestCafe has two ways of driving a browser and they behave completely differently around CAPTCHA. The original one is a web proxy called hammerhead. It sits between the browser and the site, injects its automation scripts into every page, and rewrites every URL on the resource so it points back at the proxy. That is what let TestCafe support any browser without a driver, and it is also what breaks reCAPTCHA.<\/p>\n
Two failures show up on the proxy, both reported against hammerhead and neither fixable from your test. reCAPTCHA tries to start a web worker from Google’s origin and the browser refuses, because the document’s origin is now the proxy’s own host and port. And pages served through the proxy come back with a reCAPTCHA v3 score of 0.1 every time, which most sites treat as a bot outright.<\/p>\n
Native automation replaced all of that. TestCafe drives Chromium over the DevTools protocol instead, so there is no proxy in the path and no URL rewriting at all. It landed as an experiment in v2.5.0 and it has been the default since v3.0.0. If your suite is on a current TestCafe and running in Chrome, you already have it.<\/p>\n
So the first debugging step is to confirm nothing has switched it off. TestCafe disables native automation automatically on Firefox and Safari, and the CLI flag named disable-native-automation plus its config file twin turn it off on Chromium too. Suites that added that flag years ago to work around something else are the common case. Search for it before you write any solver code.<\/p>\n
\n# Run in Chrome, which uses native automation by default.\nnpx testcafe chrome tests\/checkout.js\n\n# This flag puts you back on the proxy and breaks reCAPTCHA.\n# npx testcafe chrome tests\/checkout.js --disable-native-automation<\/pre>\n<\/div>\nOne thing is worth saying plainly, because TestCafe says it too: if you own the site under test, the best answer is not to solve anything. Google publishes a v2 test sitekey that always passes, and setting up a separate v3 key with a relaxed threshold is a five minute change in the reCAPTCHA console. TestCafe’s own reCAPTCHA recipe<\/a> walks through both. Solving is for the cases where that door is closed: a third party checkout inside the flow, a staging environment sharing production keys, or a smoke test that has to run against the real site.<\/p>\n
Step 1: read the sitekey out of the page<\/h2>\n
Selectors in TestCafe are lazy and they retry, so a selector written before the widget renders still resolves once it appears. Pull the sitekey off the widget element rather than pasting a literal into the test, and the same test survives a key rotation.<\/p>\n
\n\/\/ npm install capskip\nimport { Selector } from 'testcafe';\n\nconst PAGE_URL = 'https:\/\/example.com\/page-with-recaptcha';\n\nfixture('Checkout').page(PAGE_URL);\n\ntest('submits behind reCAPTCHA', async t => {\n const widget = Selector('.g-recaptcha');\n const sitekey = await widget.getAttribute('data-sitekey');\n});<\/pre>\n<\/div>\nStep 2: solve it from the test file<\/h2>\n
Here is where TestCafe is easier than the browser side runners. Your test function is ordinary Node, so the SDK is a plain import and the call is a plain await. There is no bridge to build and no task to register, which is the part people expect to need after coming from Cypress.<\/p>\n
\n\/\/ npm install capskip\nimport { CapSkip } from 'capskip';\n\n\/\/ Local mode. Change only the host to talk to a solver\n\/\/ running on another machine.\nconst solver = new CapSkip({ host: '127.0.0.1', port: 8080 });\n\nconst result = await solver.recaptcha(sitekey, PAGE_URL);\nconst token = result.code;<\/pre>\n<\/div>\nThat one method covers reCAPTCHA v2, Invisible, Enterprise and v3. The variants are options on the third argument rather than separate calls: invisible set to 1, enterprise set to 1, or version set to v3 with an action string. Turnstile and GeeTest have their own methods with the same shape. Every parameter is listed in the CapSkip API documentation<\/a>.<\/p>\n
Step 3: write the token in with a ClientFunction<\/h2>\n
The response field is a hidden textarea, so the normal typing action will not touch it. TestCafe actions only work on visible elements, and that is deliberate. A ClientFunction runs your code inside the page instead, which is the right tool for a field a real user never types into.<\/p>\n
The trap here catches almost everyone once. A ClientFunction cannot see variables from the surrounding test.<\/strong> The function body is serialised and shipped to the browser, so a token captured from the enclosing scope arrives as an undefined identifier at run time. Pass it as an argument or as a declared dependency.<\/p>\n
\n\/\/ The token is a parameter, not a closure variable.\nimport { ClientFunction } from 'testcafe';\n\nconst injectToken = ClientFunction(value => {\n const field = document.getElementById('g-recaptcha-response');\n field.value = value;\n field.dispatchEvent(new Event('change', { bubbles: true }));\n});\n\nawait injectToken(token);<\/pre>\n<\/div>\nTestCafe’s guidance is not to use client functions to permanently alter how a site behaves, and that guidance is worth keeping. Writing one value into one form field for one run is not that. You are filling in a field rather than patching the page’s behaviour, and the value is gone the moment the run ends.<\/p>\n
Some forms wait on a callback instead of reading the textarea. If the widget declares a data-callback attribute, invoke that function with the token in the same ClientFunction and the page proceeds exactly as it does for a human.<\/p>\n
Full working example<\/h2>\n
The whole test. Read the sitekey, solve, inject, submit, assert.<\/p>\n
\n\/\/ npm install capskip\nimport { Selector, ClientFunction } from 'testcafe';\nimport { CapSkip, NetworkException } from 'capskip';\n\nconst PAGE_URL = 'https:\/\/example.com\/page-with-recaptcha';\nconst solver = new CapSkip({ host: '127.0.0.1', port: 8080 });\n\nconst injectToken = ClientFunction(value => {\n const field = document.getElementById('g-recaptcha-response');\n field.value = value;\n field.dispatchEvent(new Event('change', { bubbles: true }));\n});\n\nfixture('Checkout').page(PAGE_URL);\n\ntest('submits the protected form', async t => {\n const sitekey = await Selector('.g-recaptcha').getAttribute('data-sitekey');\n\n let token;\n try {\n token = (await solver.recaptcha(sitekey, PAGE_URL)).code;\n } catch (err) {\n if (err instanceof NetworkException) {\n throw new Error('CapSkip is not reachable on 127.0.0.1:8080.');\n }\n throw err;\n }\n\n await injectToken(token);\n await t.click(Selector('button[type=submit]'));\n await t.expect(Selector('.thank-you').exists).ok();\n});<\/pre>\n<\/div>\nSolve as late as you can. A token is single use and it expires in about two minutes, so a token solved in a fixture hook that runs before three other tests is dead by the time the fourth one submits it. Put the call in the test that needs it.<\/p>\n
Timeouts, and the one that actually bites<\/h2>\n
A reCAPTCHA solve takes tens of seconds, which is longer than several TestCafe defaults. The good news is that the timeouts people reach for first are not involved. Your solver call is an await inside the test function rather than a page action, so the selector timeout of 10 seconds and the assertion timeout of 3 seconds never see it.<\/p>\n
The limit that matters is the test execution timeout, which caps how long a single test may run. It has no default, so it only bites once someone sets it. If your CI config passes a test execution timeout, make sure the value leaves room for a slow solve on top of everything else the test does. The SDK has its own ceiling too: recaptchaTimeout defaults to 300 seconds and raises a TimeoutException when a solve outlasts it.<\/p>\n
Running the solver somewhere else<\/h2>\n
Tests move to CI, and a CI runner is not your desk. Nothing in the code above changes except the host string.<\/p>\n
CapSkip has two connection modes. Local binds to 127.0.0.1 and answers that device only, which is what you want while you are writing the test. Server binds to your network or public IP, so a build agent, a container or a VM calls the same Windows machine over the API. A static public IP keeps that address stable. It is your hardware and it stays unmetered in both modes, so a suite that solves five hundred a night costs exactly what a suite that solves five does.<\/p>\n
\n\/\/ Same SDK, same call. Only the host moves.\nconst solver = new CapSkip({\n host: process.env.CAPSKIP_HOST || '127.0.0.1',\n port: 8080,\n apiKey: process.env.CAPSKIP_API_KEY,\n});<\/pre>\n<\/div>\nThe SDK reads CAPSKIP_HOST, CAPSKIP_PORT and CAPSKIP_API_KEY from the environment on its own, so a CI job can point the same test file at a remote solver with two variables and no code change. Turn on key validation once the solver listens on a network address, and give each runner its own key so one can be revoked without touching the others. Both modes are walked through in the CapSkip setup guide<\/a>.<\/p>\n
Common errors and what they mean<\/h2>\n