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

Modifier and Type	Method and 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.

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(long, java.util.concurrent.TimeUnit) 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(long, java.util.concurrent.TimeUnit)