Execute JavaScript with the SDK

Selenium WebDriver can run JavaScript in the current browser window. In webmate tests, this is useful for reading browser-side state, scrolling to elements, or calling application hooks that are not exposed through standard WebDriver commands.

Use script execution as an escape hatch, not as the default way to automate a page. Prefer normal WebDriver actions for clicking, typing, waiting, and asserting visible behavior. Script execution can bypass the same user interactions that your test should verify.

Prerequisites

Start with a working webmate Selenium test. The examples below assume that you already created a RemoteWebDriver for webmate and opened the page under test.

If you are setting up your first test, see Getting Started . For webmate SDK helpers, see Using the SDK . For slot and browser selection, see Selenium Capabilities in webmate .

Create a Script Executor

In Java, cast the active driver to Selenium’s JavascriptExecutor before running scripts:

1

JavascriptExecutor js = (JavascriptExecutor) driver;

The script runs in the context of the current window or frame. If your test switched into an embedded frame, the script also runs there. Switch back to the correct frame before executing a script that expects the top page.

Read Browser State

Use executeScript when you need a value from the page that is difficult to retrieve through normal element APIs. Always return the smallest value your test needs.

1
2
3
4
5
6

JavascriptExecutor js = (JavascriptExecutor) driver;

String title = (String) js.executeScript("return document.title;");
Boolean hasErrors = (Boolean) js.executeScript(
    "return document.querySelectorAll('.error, [aria-invalid=\"true\"]').length > 0;"
);

Return values are converted to Java values by Selenium. For example, a JavaScript string becomes a Java String, a boolean becomes a Boolean, and an element can be returned as a WebElement.

Pass Elements as Arguments

Do not build scripts by concatenating selectors or user-provided values. Find elements with WebDriver first and pass them as script arguments. Selenium exposes those arguments as arguments[0], arguments[1], and so on.

1
2
3
4

JavascriptExecutor js = (JavascriptExecutor) driver;
WebElement footer = driver.findElement(By.cssSelector("footer"));

js.executeScript("arguments[0].scrollIntoView({block: 'center'});", footer);

This pattern keeps locator logic in WebDriver and avoids quoting problems inside the JavaScript string.

Wait for Browser-Side Work

Use asynchronous script execution when the page needs to complete browser-side work before the test can continue. The last argument is a callback supplied by Selenium. Call it exactly once with the result.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

driver.manage().timeouts().scriptTimeout(Duration.ofSeconds(10));

JavascriptExecutor js = (JavascriptExecutor) driver;
String readyState = (String) js.executeAsyncScript("""
    const done = arguments[arguments.length - 1];
    if (document.readyState === 'complete') {
        done(document.readyState);
        return;
    }
    window.addEventListener('load', () => done(document.readyState), { once: true });
""");

Keep asynchronous scripts short and set a reasonable script timeout in your test setup. A callback that is never called will block until the timeout is reached.

Use Script Execution Carefully

Script execution is powerful, but it can make tests less realistic. Avoid it when a normal user action or WebDriver wait would verify the same behavior.

Good use cases include:

• reading page data,
• scrolling an element into view before a normal WebDriver action,
• checking a browser API result that is not visible in the page,
• calling a test-only hook in your own application,
• and collecting diagnostic information after a failure.

Avoid using scripts to:

• click controls that a user could not click,
• fill hidden fields,
• force application state that the user interface does not allow,
• bypass validation,
• or hide timing problems instead of fixing waits.

Complete Example

The following example opens a page, reads the title through JavaScript, scrolls to a footer element, and waits for the browser to report that the document is ready.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37

DesiredCapabilities caps = new DesiredCapabilities();
caps.setCapability("wm:apikey", "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx=");
caps.setCapability("wm:project", "7c4f09fd-xxx-xxx-xxx-xxx");
caps.setCapability("browserName", "CHROME");
caps.setCapability("browserVersion", "126");
caps.setCapability("platformName", "WINDOWS_11_64");

RemoteWebDriver driver = new RemoteWebDriver(
    new URL("https://selenium.webmate.io/wd/hub"),
    caps
);

try {
    driver.get("https://www.examplepage.org/");

    JavascriptExecutor js = (JavascriptExecutor) driver;

    String title = (String) js.executeScript("return document.title;");
    System.out.println("Page title: " + title);

    WebElement footer = driver.findElement(By.cssSelector("footer"));
    js.executeScript("arguments[0].scrollIntoView({block: 'center'});", footer);

    driver.manage().timeouts().scriptTimeout(Duration.ofSeconds(10));
    String readyState = (String) js.executeAsyncScript("""
        const done = arguments[arguments.length - 1];
        if (document.readyState === 'complete') {
            done(document.readyState);
            return;
        }
        window.addEventListener('load', () => done(document.readyState), { once: true });
    """);

    System.out.println("Document ready state: " + readyState);
} finally {
    driver.quit();
}

Clean Up the Device

When the test is finished, close the browser session and release the device. If you manage devices directly through the webmate API, wait until the asynchronous delete operation has completed before starting another test that depends on the same slot. See Interact with Devices for device release helpers.