Package org.openqa.selenium

Interface JavascriptExecutor

All Known Implementing Classes:
ChromeDriver, ChromiumDriver, EdgeDriver, FirefoxDriver, InternetExplorerDriver, RemoteWebDriver, SafariDriver
@NullMarked public interface JavascriptExecutor
Indicates that a driver can execute JavaScript, providing access to the mechanism to do so.

Because of cross domain policies browsers enforce your script execution may fail unexpectedly and without adequate error messaging. This is particularly pertinent when creating your own XHR request or when trying to access another frame. Most times when troubleshooting failure it's best to view the browser's console after executing the WebDriver request.

  • Method Summary

    Modifier and Type
    Method
    Description
    @Nullable Object
    executeAsyncScript(String script, @Nullable Object... args)
    Execute an asynchronous piece of JavaScript in the context of the currently selected frame or window.
    @Nullable Object
    executeScript(String script, @Nullable Object... args)
    Executes JavaScript in the context of the currently selected frame or window.
    default @Nullable Object
    executeScript(ScriptKey key, @Nullable Object... args)
    Calls a script by the ScriptKey returned by pin(String).
    default Set<ScriptKey>
    getPinnedScripts()
     
    default ScriptKey
    pin(String script)
    Commonly used scripts may be "pinned" to the WebDriver session, allowing them to be called efficiently by their handle rather than sending the entire script across the wire for every call.
    default void
    unpin(ScriptKey key)
    Deletes the reference to a script that has previously been pinned.

  • Method Details

    • executeScript

      @Nullable Object executeScript(String script, @Nullable Object... args)
      Executes JavaScript in the context of the currently selected frame or window. The script fragment provided will be executed as the body of an anonymous function.

      Within the script, use document to refer to the current document. Note that local variables will not be available once the script has finished executing, though global variables will persist.

      If the script has a return value (i.e. if the script contains a return statement), then the following steps will be taken:

      • For an HTML element, this method returns a WebElement
      • For a decimal, a Double is returned
      • For a non-decimal number, a Long is returned
      • For a boolean, a Boolean is returned
      • For all other cases, a String is returned.
      • For an array, return a List<Object> with each object following the rules above. We support nested lists.
      • For a map, return a Map<String, Object> with values following the rules above.
      • Unless the value is null or there is no return value, in which null is returned

      Arguments must be a number, a boolean, a String, WebElement, or a List of any combination of the above. An exception will be thrown if the arguments do not meet these criteria. The arguments will be made available to the JavaScript via the "arguments" magic variable, as if the function were called via "Function.apply"

      Parameters:
      script - The JavaScript to execute
      args - The arguments to the script. May be empty
      Returns:
      One of Boolean, Long, Double, String, List, Map or WebElement. Or null.

    • executeAsyncScript

      @Nullable Object executeAsyncScript(String script, @Nullable Object... args)
      Execute an asynchronous piece of JavaScript in the context of the currently selected frame or window. Unlike executing synchronous JavaScript, scripts executed with this method must explicitly signal they are finished by invoking the provided callback. This callback is always injected into the executed function as the last argument.

      The first argument passed to the callback function will be used as the script's result. This value will be handled as follows:

      • For an HTML element, this method returns a WebElement
      • For a number, a Long is returned
      • For a boolean, a Boolean is returned
      • For all other cases, a String is returned.
      • For an array, return a List<Object> with each object following the rules above. We support nested lists.
      • For a map, return a Map<String, Object> with values following the rules above.
      • Unless the value is null or there is no return value, in which null is returned

      The default timeout for a script to be executed is 0ms. In most cases, including the examples below, one must set the script timeout WebDriver.Timeouts.scriptTimeout(java.time.Duration) beforehand to a value sufficiently large enough.

      Example #1: Performing a sleep in the browser under test. 

      
 long start = System.currentTimeMillis();
 ((JavascriptExecutor) driver).executeAsyncScript(
     "window.setTimeout(arguments[arguments.length - 1], 500);");
 System.out.println(
     "Elapsed time: " + (System.currentTimeMillis() - start));

      Example #2: Synchronizing a test with an AJAX application: 

      
 WebElement composeButton = driver.findElement(By.id("compose-button"));
 composeButton.click();
 ((JavascriptExecutor) driver).executeAsyncScript(
     "var callback = arguments[arguments.length - 1];" +
     "mailClient.getComposeWindowWidget().onload(callback);");
 driver.switchTo().frame("composeWidget");
 driver.findElement(By.id("to")).sendKeys("bog@example.com");

      Example #3: Injecting a XMLHttpRequest and waiting for the result: 

      
 Object response = ((JavascriptExecutor) driver).executeAsyncScript(
     "var callback = arguments[arguments.length - 1];" +
     "var xhr = new XMLHttpRequest();" +
     "xhr.open('GET', '/resource/data.json', true);" +
     "xhr.onreadystatechange = function() {" +
     "  if (xhr.readyState == 4) {" +
     "    callback(xhr.responseText);" +
     "  }" +
     "};" +
     "xhr.send();");
 JsonObject json = new JsonParser().parse((String) response);
 assertEquals("cheese", json.get("food").getAsString());

      Script arguments must be a number, a boolean, a String, WebElement, or a List of any combination of the above. An exception will be thrown if the arguments do not meet these criteria. The arguments will be made available to the JavaScript via the "arguments" variable.

      Parameters:
      script - The JavaScript to execute.
      args - The arguments to the script. May be empty.
      Returns:
      One of Boolean, Long, String, List, Map, WebElement, or null.
      See Also:

    • pin

      default ScriptKey pin(String script)
      Commonly used scripts may be "pinned" to the WebDriver session, allowing them to be called efficiently by their handle rather than sending the entire script across the wire for every call.

      The default implementation of this adheres to the API's expectations but is inefficient.

      Parameters:
      script - The Javascript to execute.
      Returns:
      A handle which may later be used in executeScript(ScriptKey, Object...)
      Throws:
      JavascriptException - If the script cannot be pinned for some reason.
      See Also:

    • unpin

      default void unpin(ScriptKey key)
      Deletes the reference to a script that has previously been pinned. Subsequent calls to executeScript(ScriptKey, Object...) will fail for the given key.

    • getPinnedScripts

      default Set<ScriptKey> getPinnedScripts()
      Returns:
      The ScriptKeys of all currently pinned scripts.

    • executeScript

      default @Nullable Object executeScript(ScriptKey key, @Nullable Object... args)
      Calls a script by the ScriptKey returned by pin(String). This can be thought of as inlining the pinned script and simply calling executeScript(String, Object...).
      See Also: