Class webdriver.WebDriver

Defined in: webdriver.js.

Class Summary
Constructor Attributes	Constructor Name and Description
	webdriver.WebDriver(session, executor, opt_flow) Creates a new WebDriver client, which provides control over a browser.

Method Summary
Method Attributes	Method Name and Description
	actions() Creates a new action sequence using this driver.
<static>	webdriver.WebDriver.attachToSession(executor, sessionId) Creates a new WebDriver client for an existing session.
	call(fn, opt_scope, var_args) Schedules a command to execute a custom function.
	close() Schedules a command to close the current window.
	controlFlow()
<static>	webdriver.WebDriver.createSession(executor, desiredCapabilities) Creates a new WebDriver session.
	executeAsyncScript(script, var_args) Schedules a command to execute asynchronous JavaScript in the context of the currently selected frame or window.
	executeScript(script, var_args) Schedules a command to execute JavaScript in the context of the currently selected frame or window.
	findElement(locatorOrElement, var_args) Schedule a command to find an element on the page.
	findElements(locator, var_args) Schedule a command to search for multiple elements on the page.
	get(url) Schedules a command to navigate to the given URL.
	getAllWindowHandles() Schedules a command to retrieve the current list of available window handles.
	getCapabilities()
	getCapability(name) Returns a promise for one of this driver's capabilities.
	getCurrentUrl() Schedules a command to retrieve the URL of the current page.
	getPageSource() Schedules a command to retrieve the current page's source.
	getSession()
	getTitle() Schedules a command to retrieve the current page's title.
	getWindowHandle() Schedules a command to retrieve they current window handle.
	isElementPresent(locatorOrElement, var_args) Schedules a command to test if an element is present on the page.
	manage()
	navigate()
	quit() Schedules a command to quit the current session.
	schedule(command, description) Schedules a {@code webdriver.Command} to be executed by this driver's {@code webdriver.CommandExecutor}.
	sleep(ms) Schedules a command to make the driver sleep for the given amount of time.
	switchTo()
	takeScreenshot() Schedule a command to take a screenshot.
	wait(fn, timeout, opt_message) Schedules a command to wait for a condition to hold, as defined by some user supplied function.

Class Detail

webdriver.WebDriver(session, executor, opt_flow)

Creates a new WebDriver client, which provides control over a browser. Every WebDriver command returns a {@code webdriver.promise.Promise} that represents the result of that command. Callbacks may be registered on this object to manipulate the command result or catch an expected error. Any commands scheduled with a callback are considered sub-commands and will execute before the next command in the current frame. For example:


  var message = [];
  driver.call(message.push, message, 'a').then(function() {
    driver.call(message.push, message, 'b');
  });
  driver.call(message.push, message, 'c');
  driver.call(function() {
    alert('message is abc? ' + (message.join('') == 'abc'));
  });

Parameters:
{!(webdriver.Session|webdriver.promise.Promise)} session: Either a known session or a promise that will be resolved to a session.
{!webdriver.CommandExecutor} executor: The executor to use when sending commands to the browser.
{webdriver.promise.ControlFlow=} opt_flow: The flow to schedule commands through. Defaults to the active flow object.

Method Detail

{!webdriver.ActionSequence} actions()

Creates a new action sequence using this driver. The sequence will not be scheduled for execution until webdriver.ActionSequence#perform is called. Example:


  driver.actions().
      mouseDown(element1).
      mouseMove(element2).
      mouseUp().
      perform();

Returns:: {!webdriver.ActionSequence} A new action sequence for this instance.

<static> {!webdriver.WebDriver} webdriver.WebDriver.attachToSession(executor, sessionId)

Creates a new WebDriver client for an existing session.

Parameters:
{!webdriver.CommandExecutor} executor: Command executor to use when querying for session details.
{string} sessionId: ID of the session to attach to.

Returns:: {!webdriver.WebDriver} A new client for the specified session.

{!webdriver.promise.Promise} call(fn, opt_scope, var_args)

Schedules a command to execute a custom function.

Parameters:
{!Function} fn: The function to execute.
{Object=} opt_scope: The object in whose scope to execute the function.
{...*} var_args: Any arguments to pass to the function.

Returns:: {!webdriver.promise.Promise} A promise that will be resolved with the function's result.

{!webdriver.promise.Promise} close()

Schedules a command to close the current window.

Returns:: {!webdriver.promise.Promise} A promise that will be resolved when this command has completed.

{!webdriver.promise.ControlFlow} controlFlow()

Returns:: {!webdriver.promise.ControlFlow} The control flow used by this instance.

<static> {!webdriver.WebDriver} webdriver.WebDriver.createSession(executor, desiredCapabilities)

Creates a new WebDriver session.

Parameters:
{!webdriver.CommandExecutor} executor: The executor to create the new session with.
{!webdriver.Capabilities} desiredCapabilities: The desired capabilities for the new session.

Returns:: {!webdriver.WebDriver} The driver for the newly created session.

{!webdriver.promise.Promise} executeAsyncScript(script, var_args)

Schedules a command to execute asynchronous JavaScript in the context of the currently selected frame or window. The script fragment will be executed as the body of an anonymous function. If the script is provided as a function object, that function will be converted to a string for injection into the target window. Any arguments provided in addition to the script will be included as script arguments and may be referenced using the {@code arguments} object. Arguments may be a boolean, number, string, or {@code webdriver.WebElement}. Arrays and objects may also be used as script arguments as long as each item adheres to the types previously mentioned. Unlike executing synchronous JavaScript with {@code webdriver.WebDriver.prototype.executeScript}, scripts executed with this function must explicitly signal they are finished by invoking the provided callback. This callback will always be injected into the executed function as the last argument, and thus may be referenced with {@code arguments[arguments.length - 1]}. The following steps will be taken for resolving this functions return value against the first argument to the script's callback function:

For a HTML element, the value will resolve to a {@code webdriver.WebElement}
Null and undefined return values will resolve to null
Booleans, numbers, and strings will resolve as is
Functions will resolve to their string representation
For arrays and objects, each member item will be converted according to the rules above

Example #1: Performing a sleep that is synchronized with the currently selected window:

var start = new Date().getTime();
driver.executeAsyncScript(
    'window.setTimeout(arguments[arguments.length - 1], 500);').
    then(function() {
      console.log('Elapsed time: ' + (new Date().getTime() - start) + ' ms');
    });

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

var button = driver.findElement(By.id('compose-button'));
button.click();
driver.executeAsyncScript(
    'var callback = arguments[arguments.length - 1];' +
    'mailClient.getComposeWindowWidget().onload(callback);');
driver.switchTo().frame('composeWidget');
driver.findElement(By.id('to')).sendKEys('dog@example.com');

Example #3: Injecting a XMLHttpRequest and waiting for the result. In this example, the inject script is specified with a function literal. When using this format, the function is converted to a string for injection, so it should not reference any symbols not defined in the scope of the page under test.

driver.executeAsyncScript(function() {
  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.resposneText);
    }
  }
  xhr.send('');
}).then(function(str) {
  console.log(JSON.parse(str)['food']);
});

Parameters:
{!(string|Function)} script: The script to execute.
{...*} var_args: The arguments to pass to the script.

Returns:: {!webdriver.promise.Promise} A promise that will resolve to the scripts return value.

{!webdriver.promise.Promise} executeScript(script, var_args)

Schedules a command to execute JavaScript in the context of the currently selected frame or window. The script fragment will be executed as the body of an anonymous function. If the script is provided as a function object, that function will be converted to a string for injection into the target window. Any arguments provided in addition to the script will be included as script arguments and may be referenced using the {@code arguments} object. Arguments may be a boolean, number, string, or {@code webdriver.WebElement}. Arrays and objects may also be used as script arguments as long as each item adheres to the types previously mentioned. The script may refer to any variables accessible from the current window. Furthermore, the script will execute in the window's context, thus {@code document} may be used to refer to the current document. Any 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 resolving this functions return value:

For a HTML element, the value will resolve to a {@code webdriver.WebElement}
Null and undefined return values will resolve to null
Booleans, numbers, and strings will resolve as is
Functions will resolve to their string representation
For arrays and objects, each member item will be converted according to the rules above

Parameters:
{!(string|Function)} script: The script to execute.
{...*} var_args: The arguments to pass to the script.

Returns:: {!webdriver.promise.Promise} A promise that will resolve to the scripts return value.

{!webdriver.WebElement} findElement(locatorOrElement, var_args)

Schedule a command to find an element on the page. If the element cannot be found, a {@code bot.ErrorCode.NO_SUCH_ELEMENT} result will be returned by the driver. Unlike other commands, this error cannot be suppressed. In other words, scheduling a command to find an element doubles as an assert that the element is present on the page. To test whether an element is present on the page, use {@code #isElementPresent} instead.

The search criteria for find an element may either be a {@code webdriver.Locator} object, or a simple JSON object whose sole key is one of the accepted locator strategies, as defined by {@code webdriver.Locator.Strategy}. For example, the following two statements are equivalent:

var e1 = driver.findElement(By.id('foo'));
var e2 = driver.findElement({id:'foo'});

When running in the browser, a WebDriver cannot manipulate DOM elements directly; it may do so only through a webdriver.WebElement reference. This function may be used to generate a WebElement from a DOM element. A reference to the DOM element will be stored in a known location and this driver will attempt to retrieve it through #executeScript. If the element cannot be found (eg, it belongs to a different document than the one this instance is currently focused on), a bot.ErrorCode.NO_SUCH_ELEMENT error will be returned.

Parameters:
{!(webdriver.Locator|Object.|Element)} locatorOrElement: The locator strategy to use when searching for the element, or the actual DOM element to be located by the server.
{...} var_args: Arguments to pass to {@code #executeScript} if using a JavaScript locator. Otherwise ignored.

Returns:: {!webdriver.WebElement} A WebElement that can be used to issue commands against the located element. If the element is not found, the element will be invalidated and all scheduled commands aborted.

{!webdriver.promise.Promise} findElements(locator, var_args)

Schedule a command to search for multiple elements on the page.

Parameters:
{webdriver.Locator|Object.} locator: The locator strategy to use when searching for the element.
{...} var_args: Arguments to pass to {@code #executeScript} if using a JavaScript locator. Otherwise ignored.

Returns:: {!webdriver.promise.Promise} A promise that will be resolved to an array of the located webdriver.WebElements.

{!webdriver.promise.Promise} get(url)

Schedules a command to navigate to the given URL.

Parameters:
{string} url: The fully qualified URL to open.

Returns:: {!webdriver.promise.Promise} A promise that will be resolved when the document has finished loading.

{!webdriver.promise.Promise} getAllWindowHandles()

Schedules a command to retrieve the current list of available window handles.

Returns:: {!webdriver.promise.Promise} A promise that will be resolved with an array of window handles.

{!webdriver.promise.Promise} getCapabilities()

Returns:: {!webdriver.promise.Promise} A promise that will resolve with the this instance's capabilities.

{!webdriver.promise.Promise} getCapability(name)

Returns a promise for one of this driver's capabilities.

Parameters:
{string} name: The name of the capability to query.

Deprecated:
Use #getCapabilities(); this function will be removed in 2.35.0.

Returns:: {!webdriver.promise.Promise} A promise that will resolve with the given capability once its value is ready.

{!webdriver.promise.Promise} getCurrentUrl()

Schedules a command to retrieve the URL of the current page.

Returns:: {!webdriver.promise.Promise} A promise that will be resolved with the current URL.

{!webdriver.promise.Promise} getPageSource()

Schedules a command to retrieve the current page's source. The page source returned is a representation of the underlying DOM: do not expect it to be formatted or escaped in the same way as the response sent from the web server.

Returns:: {!webdriver.promise.Promise} A promise that will be resolved with the current page source.

{!webdriver.promise.Promise} getSession()

Returns:: {!webdriver.promise.Promise} A promise for this client's session.

{!webdriver.promise.Promise} getTitle()

Schedules a command to retrieve the current page's title.

Returns:: {!webdriver.promise.Promise} A promise that will be resolved with the current page's title.

{!webdriver.promise.Promise} getWindowHandle()

Schedules a command to retrieve they current window handle.

Returns:: {!webdriver.promise.Promise} A promise that will be resolved with the current window handle.

{!webdriver.promise.Promise} isElementPresent(locatorOrElement, var_args)

Schedules a command to test if an element is present on the page.

If given a DOM element, this function will check if it belongs to the document the driver is currently focused on. Otherwise, the function will test if at least one element can be found with the given search criteria.

Parameters:
{!(webdriver.Locator|Object.|Element)} locatorOrElement: The locator strategy to use when searching for the element, or the actual DOM element to be located by the server.
{...} var_args: Arguments to pass to {@code #executeScript} if using a JavaScript locator. Otherwise ignored.

Returns:: {!webdriver.promise.Promise} A promise that will resolve to whether the element is present on the page.

{!webdriver.WebDriver.Options} manage()

Returns:: {!webdriver.WebDriver.Options} The options interface for this instance.

{!webdriver.WebDriver.Navigation} navigate()

Returns:: {!webdriver.WebDriver.Navigation} The navigation interface for this instance.

{!webdriver.promise.Promise} quit()

Schedules a command to quit the current session. After calling quit, this instance will be invalidated and may no longer be used to issue commands against the browser.

Returns:: {!webdriver.promise.Promise} A promise that will be resolved when the command has completed.

{!webdriver.promise.Promise} schedule(command, description)

Schedules a {@code webdriver.Command} to be executed by this driver's {@code webdriver.CommandExecutor}.

Parameters:
{!webdriver.Command} command: The command to schedule.
{string} description: A description of the command for debugging.

Returns:: {!webdriver.promise.Promise} A promise that will be resolved with the command result.

{!webdriver.promise.Promise} sleep(ms)

Schedules a command to make the driver sleep for the given amount of time.

Parameters:
{number} ms: The amount of time, in milliseconds, to sleep.

Returns:: {!webdriver.promise.Promise} A promise that will be resolved when the sleep has finished.

{!webdriver.WebDriver.TargetLocator} switchTo()

Returns:: {!webdriver.WebDriver.TargetLocator} The target locator interface for this instance.

{!webdriver.promise.Promise} takeScreenshot()

Schedule a command to take a screenshot. The driver makes a best effort to return a screenshot of the following, in order of preference:

Entire page
Current window
Visible portion of the current frame
The screenshot of the entire display containing the browser

Returns:: {!webdriver.promise.Promise} A promise that will be resolved to the screenshot as a base-64 encoded PNG.

{!webdriver.promise.Promise} wait(fn, timeout, opt_message)

Schedules a command to wait for a condition to hold, as defined by some user supplied function. If any errors occur while evaluating the wait, they will be allowed to propagate.

Parameters:
{function():boolean} fn: The function to evaluate as a wait condition.
{number} timeout: How long to wait for the condition to be true.
{string=} opt_message: An optional message to use if the wait times out.

Returns:: {!webdriver.promise.Promise} A promise that will be resolved when the wait condition has been satisfied.

API Reference for selenium-webdriver v2.39.0

Classes

Class webdriver.WebDriver