Package org.openqa.selenium

Interface JavascriptExecutor

  • 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

      All Methods Instance Methods Abstract Methods Default Methods 
      Modifier and Type Method Description
      java.lang.Object executeAsyncScript​(java.lang.String script, java.lang.Object... args)
      Execute an asynchronous piece of JavaScript in the context of the currently selected frame or window.
      java.lang.Object executeScript​(java.lang.String script, java.lang.Object... args)
      Executes JavaScript in the context of the currently selected frame or window.
      default java.lang.Object executeScript​(ScriptKey key, java.lang.Object... args)
      Calls a script by the ScriptKey returned by pin(String).
      default java.util.Set<ScriptKey> getPinnedScripts()  
      default ScriptKey pin​(java.lang.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 Detail

      • executeScript

        java.lang.Object executeScript​(java.lang.String script,
                               java.lang.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

        java.lang.Object executeAsyncScript​(java.lang.String script,
                                    java.lang.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.setScriptTimeout(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("[email protected]");

        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:
        WebDriver.Timeouts.setScriptTimeout(java.time.Duration)

      • pin

        default ScriptKey pin​(java.lang.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:
        executeScript(ScriptKey, Object...)

      • getPinnedScripts

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