A WebdriverIO captcha step is a Node.js call, not a browser one. You solve in the test process, hand the token to the page through browser.execute, and submit the form. Two things catch people out, and neither is about the solver. Put the solve inside the browser context and it has no way to reach your machine at all. Leave Mocha on its default thirty second timeout and the test dies halfway through a solve with a message that explains nothing. Here is the custom command, the one config change, and a spec that works.<\/p>\n
# Install into the project that runs wdio, not into the browser image.\nnpm install capskip<\/pre>\n<\/div>\nSolve in Node, not in the browser<\/h2>\n
This is the mistake worth getting out of the way first, because WebdriverIO makes it easy to make. The browser.execute command serialises your function, ships it to the browser, and runs it inside the page. There is no module loader in there, so the SDK is simply not available. Even if it were, the page is the thing you are testing, and handing it the address of your solver is not a thing you want to do.<\/p>\n
The stronger reason is routing. Once the browser is anywhere but your own machine, and on a grid or a cloud device provider it never is, the loopback address inside that browser belongs to the browser host. Your solver is not there. The Node process running wdio is the one that knows how to reach CapSkip, so the solve stays there and only the finished token crosses into the page.<\/p>\n
Step 1: register a custom command<\/h2>\n
Rather than importing the SDK into every spec, add one command in the before hook of your config. It becomes available on the browser object in every test, and the address of the solver lives in exactly one place.<\/p>\n
\n\/\/ npm install capskip\nconst { CapSkip } = require('capskip');\n\nexports.config = {\n framework: 'mocha',\n\n before: function () {\n const solver = new CapSkip({\n host: process.env.CAPSKIP_HOST || '127.0.0.1',\n port: Number(process.env.CAPSKIP_PORT || 8080),\n });\n\n browser.addCommand('solveRecaptcha', async function (sitekey) {\n const result = await solver.recaptcha(sitekey, await this.getUrl());\n return result.code; \/\/ the token, ready to inject\n });\n },\n};<\/pre>\n<\/div>\nInside addCommand the this value is the browser scope, which is why getUrl works there. That detail is doing real work: the API wants the URL of the page the widget sits on, and asking the browser for it means the spec never has to repeat a URL it already navigated to.<\/p>\n
Read the host from the environment instead of hardcoding it. The same suite then runs against a solver on your laptop and against a shared one from CI without a code change.<\/p>\n
Step 2: inject the token and submit<\/h2>\n
Google puts the answer in a hidden textarea with the id g-recaptcha-response. It is hidden, so no amount of setValue will touch it. Set the value directly and then submit the form the way a person would.<\/p>\n
\nconst token = await browser.solveRecaptcha('YOUR_SITEKEY');\n\n\/\/ Put the token where the page already expects to find it.\nawait browser.execute((value) => {\n document.getElementById('g-recaptcha-response').value = value;\n}, token);\n\nawait $('button[type="submit"]').click();<\/pre>\n<\/div>\nThat covers the common case, which is a form that reads the textarea when you press submit. Some pages instead declare a data-callback on the widget and never look at the textarea at all. When that is what you are testing, call the callback from the same browser.execute block after setting the value, because filling a field nobody reads changes nothing.<\/p>\n
Step 3: raise the Mocha timeout<\/h2>\n
WebdriverIO defaults Mocha to a 30000 millisecond timeout, which is generous for clicking things and much too short for solving a challenge. A test that would otherwise pass fails here, and the failure names Mocha rather than anything to do with the solve, which sends people looking in the wrong place for an afternoon.<\/p>\n
\nexports.config = {\n framework: 'mocha',\n mochaOpts: {\n \/\/ The 30000 default expires mid solve. Give it room.\n timeout: 120000,\n },\n};<\/pre>\n<\/div>\nSet the two limits in the right order. The SDK gives up after recaptchaTimeout, which defaults to 300 seconds, and Mocha gives up after its own timeout. Keep the SDK below Mocha and you get a TimeoutException naming the solve. Keep it above and Mocha kills the test first, and all you learn is that something took too long. A solver timeout of 90 seconds under a Mocha timeout of 120000 milliseconds is a sane pair for a suite that has to stay quick.<\/p>\n
Running it on CI or a grid<\/h2>\n
Work out which machine needs to reach the solver, because it is not the obvious one. The browser never talks to CapSkip. The process running wdio does. So on a GitHub Actions runner, a container, or a laptop driving a cloud browser, the caller is that runner, and pointing it at its own loopback address finds nothing.<\/p>\n