In Selenium, how does a script run by executeAsyncScript signal completion, and what happens if it never signals?

## What the async variant is for `executeScript` finishes when the function body returns. That is useless when the value you want does not exist yet - a tax-return summary page that fetches the refund figure over the network and paints it when the response lands. `executeAsyncScript` exists for that case: the command stays open until the page tells it the work is done. The signalling mechanism is **positional and injected**. Selenium sends your arguments, and the remote end appends one extra value to the end of the argument list: a **callback function**. Inside the script it is therefore `arguments[arguments.length - 1]`, whatever you passed before it. The first value handed to that callback becomes the command's result and is marshalled back to Java by the same rules `executeScript` uses. ```java driver.manage().timeouts().scriptTimeout(Duration.ofSeconds(10)); Object refund = ((JavascriptExecutor) driver).executeAsyncScript( "const done = arguments[arguments.length - 1];" + "fetch('/api/return/2025/refund').then(r => r.json())" + " .then(d => done(d.refundPence)).catch(e => done(-1));"); ``` ## Sync against async | | `executeScript` | `executeAsyncScript` | |---|---|---| | Endpoint | `/session/{id}/execute/sync` | `/session/{id}/execute/async` | | Result comes from | the script's `return` value | the injected callback's first argument | | Extra injected argument | none | the callback, always last | | Ends when | the function body returns | the callback fires, or the timer expires | | Timeout breach | `ScriptTimeoutException` | `ScriptTimeoutException` | | Script throws | `JavascriptException` | `JavascriptException` | Both commands are governed by the same **script timeout**, whose W3C initial value is **30,000 ms**. In Selenium 4 you change it with `driver.manage().timeouts().scriptTimeout(Duration)` and read it back with `getScriptTimeout()`; the Selenium 3 spelling `Timeouts.setScriptTimeout(long, TimeUnit)` no longer exists on that interface. ## The three ways it goes wrong 1. **The callback is never called.** The remote end waits, the timer fires, and the command returns the `script timeout` error, which the Java client throws as `ScriptTimeoutException`. Nothing about the message points at your missing call, so this is the failure people misread as "the page is slow". 2. **The callback is called on only one path.** A `fetch` chain with a `then` but no `catch` signals on success and hangs forever on a rejected promise, so a backend error surfaces as a timeout instead of as itself. Always signal on both branches. 3. **The script uses `return` instead.** A plain returned value does not end the command. The W3C algorithm only honours a returned value when it is a **thenable**, in which case the command resolves with the promise's fulfilment value; a returned string or number is ignored and the command still waits for the callback. ## Signalling failure without hanging - Pass a sentinel, not an exception: call `done(null)` or `done({error: e.message})` from the `catch` branch so the Java side gets a value it can assert on. - Only the **first** call to the callback counts; later calls are ignored, so a defensive extra call is harmless. - Anything the callback receives is JSON-cloned. Functions, DOM ranges and circular objects do not survive the trip; send a plain object, a number or a string. - An element handed to the callback comes back as a live `WebElement`, so `done(document.querySelector('#refund'))` is a valid way to return a node. ## Where it belongs and where it does not `executeAsyncScript` is a narrow tool. - It fits when the page owns a promise you can attach to: a `fetch`, a widget's `onload`, an app-provided readiness hook the team controls. - It fits when the value you want never reaches the DOM at all, so no amount of polling from the client would ever see it. - It does not fit as a general "wait for the page" mechanism. A polling wait in Java re-reads the DOM through normal commands and names the condition that never came true, while a hung async script reports only that the timer expired. - It couples the suite to the application's internals, because the script has to know which promise to attach to. Two practical habits keep it usable. First, set the script timeout to something you chose rather than inheriting the default, because a 30-second stall is a long time to spend in a suite. Second, keep the injected body short enough to read in the failure message - a long inline string is the hardest thing in a Selenium codebase to debug, because the browser console holds the real error and your Java stack trace holds only `JavascriptException`. ## The mental model Treat the callback as the **return statement of a function whose end you do not control**. `executeScript` asks the page a question and waits for the sentence to finish. `executeAsyncScript` hands the page a pen and waits for it to write - and if the page never writes, only the clock ends the command.