org.openqa.selenium.JavascriptExecutor Maven / Gradle / Ivy
Show all versions of selenium-api Show documentation
/*
Copyright 2007-2009 Selenium committers
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
*/
package org.openqa.selenium;
/**
* Indicates that a driver can execute JavaScript, providing access to the mechanism to do so.
*/
public interface JavascriptExecutor {
/**
* 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.
* - 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"
*
* @param script The JavaScript to execute
* @param args The arguments to the script. May be empty
* @return One of Boolean, Long, String, List or WebElement. Or null.
*/
Object executeScript(String script, Object... args);
/**
* Execute an asynchronous piece of JavaScript in the context of the currently selected frame or
* window. Unlike executing {@link #executeScript(String, Object...) 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.
* - Unless the value is null or there is no return value, in which null is returned
*
*
*
* 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 JSONObject((String) response);
* assertEquals("cheese", json.getString("food"));
*
* 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.
*
* @param script The JavaScript to execute.
* @param args The arguments to the script. May be empty.
* @return One of Boolean, Long, String, List, WebElement, or null.
*/
Object executeAsyncScript(String script, Object... args);
}