A Nightwatch captcha solve has to run inside the command queue, not beside it. Nightwatch does not execute browser commands where you wrote them. It queues them and drains the queue after your test function returns, so a solving call written between two browser commands fires immediately, before the page has loaded and before the widget exists. The fix is browser.perform, plus one global you have to raise because a solve takes longer than the ten seconds Nightwatch allows an async callback.<\/p>\n
# npm install capskip\nnpm install --save-dev nightwatch\nnpm install capskip<\/pre>\n<\/div>\nStep 1: why a plain solving call runs too early<\/h2>\n
Every browser command in a Nightwatch test is an instruction added to a queue. The test function runs top to bottom first, building that queue, and only then does Nightwatch start executing it. Ordinary JavaScript in between is not part of the queue, so it runs during the building pass. That is the whole problem in one sentence.<\/p>\n
\n\/\/ WRONG. The solve starts while the queue is still being\n\/\/ built, so it runs before browser.url() has navigated.\nmodule.exports = {\n "signup form": function (browser) {\n browser.url("https:\/\/example.com\/page-with-recaptcha");\n\n solver.recaptcha(sitekey, pageUrl).then((r) => {\n \/\/ fires first, against a page that is not open yet\n });\n\n browser.click("#submit");\n },\n};<\/pre>\n<\/div>\nThe symptom is confusing because nothing throws. The solve succeeds, the test passes sometimes, and the token is for a page load that never happened. Nightwatch gives you a documented way to put your own code into the queue instead: browser.perform, whose callback is described as the function to run as part of the queue.<\/p>\n
\n\/\/ RIGHT. perform() queues the callback, so it runs in\n\/\/ sequence with the commands either side of it.\nbrowser.url("https:\/\/example.com\/page-with-recaptcha");\n\nbrowser.perform(async function () {\n const { code } = await solver.recaptcha(sitekey, pageUrl);\n return code;\n});\n\nbrowser.click("#submit");<\/pre>\n<\/div>\nAn async test is the other option. Declaring the test function async makes the API commands return a promise, so awaiting each one keeps everything in order without perform. Both work. The mistake is mixing them: an awaited external promise sitting among unawaited browser commands puts you back in the first example.<\/p>\n
Step 2: raise asyncHookTimeout, or the solve times out at ten seconds<\/h2>\n
This is the one that wastes an afternoon. Asynchronous execution inside perform is bounded by the asyncHookTimeout global, and that default is 10000 milliseconds. A reCAPTCHA solve regularly takes fifteen to forty-five seconds. So the callback is killed while the solver is still working, and the error you get talks about a timeout rather than about the CAPTCHA.<\/p>\n
Raise it in your Nightwatch config, globally or per environment.<\/p>\n
\n\/\/ nightwatch.conf.js\nmodule.exports = {\n globals: {\n \/\/ Default is 10000, which is shorter than most solves.\n asyncHookTimeout: 120000,\n\n \/\/ waitFor commands default to 5000. The widget is not\n \/\/ the slow part, but give it room on a cold CI runner.\n waitForConditionTimeout: 15000,\n },\n};<\/pre>\n<\/div>\nSet the client side to sit under it, so one ceiling is clearly the effective one. The Node client polls on its own schedule, starting at 250 milliseconds and backing off to pollingInterval, which is why it usually returns sooner than a hand-written loop.<\/p>\n
\n\/\/ npm install capskip\nconst { CapSkip } = require("capskip");\n\nconst solver = new CapSkip({\n host: process.env.CAPSKIP_HOST || "127.0.0.1",\n port: 8080,\n \/\/ Seconds. Keep this under the 120s asyncHookTimeout above.\n recaptchaTimeout: 90,\n pollingInterval: 3,\n});<\/pre>\n<\/div>\nStep 3: inject the token with execute, not setValue<\/h2>\n
The response field reCAPTCHA reads is a hidden textarea. WebDriver refuses to interact with elements it considers non-interactable, so setValue on it fails with an element not interactable error. Injecting through the page is the normal answer, and Nightwatch exposes it as execute, which takes a function body, an argument array and an optional callback.<\/p>\n
\nbrowser.perform(async function () {\n const { code } = await solver.recaptcha(sitekey, pageUrl);\n\n \/\/ The function is serialized and run in the page, so it\n \/\/ cannot close over anything. Pass values in the array.\n await browser.execute(\n function (token) {\n document.getElementById("g-recaptcha-response").value = token;\n },\n [code]\n );\n});<\/pre>\n<\/div>\nIf the form runs a callback on completion rather than reading the field at submit time, call it in the same script. Invisible reCAPTCHA almost always works that way, and the widget variants only change the options you pass: invisible or enterprise set to 1, version set to v3 with an action, or turnstile and geetest instead of recaptcha. The full surface is on the Node.js CAPTCHA solver page<\/a>.<\/p>\n
Step 4: the full test<\/h2>\n
The client is constructed once at module scope, outside the test, so it is not rebuilt per test case. The sitekey is read from the page rather than hardcoded, which is what makes the same spec run against staging and production.<\/p>\n
\n\/\/ npm install capskip\nconst { CapSkip } = require("capskip");\n\nconst solver = new CapSkip({\n host: process.env.CAPSKIP_HOST || "127.0.0.1",\n port: 8080,\n recaptchaTimeout: 90,\n});\n\nconst PAGE = "https:\/\/example.com\/page-with-recaptcha";\n\ndescribe("signup", function () {\n it("submits through the reCAPTCHA", async function (browser) {\n await browser.url(PAGE);\n await browser.waitForElementPresent(".g-recaptcha", 15000);\n\n \/\/ Read the sitekey off the widget that is actually there.\n const sitekey = await browser.getAttribute(\n ".g-recaptcha",\n "data-sitekey"\n );\n\n await browser.perform(async function () {\n const { code } = await solver.recaptcha(sitekey.value, PAGE);\n await browser.execute(\n function (token) {\n document.getElementById("g-recaptcha-response").value = token;\n },\n [code]\n );\n });\n\n \/\/ Submit straight after. The token is not a long-lived value.\n await browser.click("#submit");\n await browser.assert.textContains(".result", "Thanks");\n });\n});<\/pre>\n<\/div>\nSolve as late as you can and submit immediately. A reCAPTCHA token is good for around two minutes, and a suite that solves in a before hook and submits three test cases later is submitting an expired one. That window is worth reading once: how long a reCAPTCHA token lasts<\/a>.<\/p>\n
Step 5: running it on CI, and which connection mode that needs<\/h2>\n
Nightwatch tests rarely stay on the machine that wrote them. The moment they move to a CI runner, a container or a Selenium Grid node, loopback stops meaning your desk. There are two connection modes. Local binds to 127.0.0.1 and answers that device only. Server binds to your network address or public IP, so a runner, a container or a grid node can reach the same Windows machine over the API. Both live under connection settings<\/a>, and Server mode only changes which address the solver listens on. It is still your hardware and it is still unmetered.<\/p>\n