# Class webdriver.WebDriver

code »

Creates a new WebDriver client, which provides control over a browser. Every WebDriver command returns a `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'));
       });

## Constructor

webdriver.WebDriver ( session, executor, opt_flow )

Parameters

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

## Classes

webdriver.WebDriver.Logs
  Interface for managing WebDriver log records.
webdriver.WebDriver.Navigation
  Interface for navigating back and forth in the browser history.
webdriver.WebDriver.Options
  Provides methods for managing browser and driver state.
webdriver.WebDriver.TargetLocator
  An interface for changing the focus of the driver to another frame or window.
webdriver.WebDriver.Timeouts
  An interface for managing timeout behavior for WebDriver instances.
webdriver.WebDriver.Window
  An interface for managing the current window.

Show:Public Protected Private

## Instance Methods

code »actions ( ) ⇒ `!webdriver.ActionSequence`

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

A new action sequence for this instance.

code »`<T>` call ( fn, opt_scope, var_args ) ⇒ `!webdriver.promise.Promise.<T>`

Schedules a command to execute a custom function.

Parameters

fn: `function(...): (T|webdriver.promise.Promise.<T>)`
  The function to execute.
opt_scope: `Object=`
  The object in whose scope to execute the function.
var_args: `...*`
  Any arguments to pass to the function.

Returns

A promise that will be resolved' with the function's result.

code »close ( ) ⇒ `!webdriver.promise.Promise.<void>`

Schedules a command to close the current window.

Returns

A promise that will be resolved when this command has completed.

code »controlFlow ( ) ⇒ `!webdriver.promise.ControlFlow`

Returns

The control flow used by this instance.

code »`<T>` executeAsyncScript ( script, var_args ) ⇒ `!webdriver.promise.Promise.<T>`

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 `arguments` object. Arguments may be a boolean, number, string, or `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 `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 `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 `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.responseText);
         }
       }
       xhr.send('');
     }).then(function(str) {
       console.log(JSON.parse(str)['food']);
     });

`

Parameters

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

Returns

A promise that will resolve to the scripts return value.

code »`<T>` executeScript ( script, var_args ) ⇒ `!webdriver.promise.Promise.<T>`

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 `arguments` object. Arguments may be a boolean, number, string, or `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 `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 `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

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

Returns

A promise that will resolve to the scripts return value.

code »findDomElement_ ( element ) ⇒ `!webdriver.promise.Promise.<webdriver.WebElement>`

Locates a DOM element so that commands may be issued against it using the `webdriver.WebElement` class. This is accomplished by storing a reference to the element in an object on the element's ownerDocument. `#executeScript` will then be used to create a WebElement from this reference. This requires this driver to currently be focused on the ownerDocument's window+frame.

Parameters

element: `!Element`
  The element to locate.

Returns

A promise that will be fulfilled with the located element, or null if the element could not be found.

code »findElement ( locator ) ⇒ `!webdriver.WebElement`

Schedule a command to find an element on the page. If the element cannot be found, a `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 `#isElementPresent` instead.

The search criteria for an element may be defined using one of the factories in the `webdriver.By` namespace, or as a short-hand `webdriver.By.Hash` object. For example, the following two statements are equivalent: ``

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

You may also provide a custom locator function, which takes as input this WebDriver instance and returns a `webdriver.WebElement`, or a promise that will resolve to a WebElement. For example, to find the first visible link on a page, you could write: ``

     var link = driver.findElement(firstVisibleLink);

     function firstVisibleLink(driver) {
       var links = driver.findElements(By.tagName('a'));
       return webdriver.promise.filter(links, function(link) {
         return links.isDisplayed();
       }).then(function(visibleLinks) {
         return visibleLinks[0];
       });
     }

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

locator: `!(webdriver.Locator|webdriver.By.Hash|Element|Function)`
  The locator to use.

Returns

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.

code »findElementInternal_ ( locatorFn, context ) ⇒ `!webdriver.promise.Promise`

Parameters

locatorFn: `!Function`
  The locator function to use.
context: `!(webdriver.WebDriver|webdriver.WebElement)`
  The search context.

Returns

A promise that will resolve to a list of WebElements.

code »findElements ( locator ) ⇒ `!webdriver.promise.Promise`

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

Parameters

locator: `!(webdriver.Locator|webdriver.By.Hash|Function)`
  The locator strategy to use when searching for the element.

Returns

A promise that will resolve to an array of WebElements.

code »findElementsInternal_ ( locatorFn, context ) ⇒ `!webdriver.promise.Promise`

Parameters

locatorFn: `!Function`
  The locator function to use.
context: `!(webdriver.WebDriver|webdriver.WebElement)`
  The search context.

Returns

A promise that will resolve to an array of WebElements.

code »get ( url ) ⇒ `!webdriver.promise.Promise.<void>`

Schedules a command to navigate to the given URL.

Parameters

url: `string`
  The fully qualified URL to open.

Returns

A promise that will be resolved when the document has finished loading.

code »getAllWindowHandles ( ) ⇒ `!webdriver.promise.Promise`

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

Returns

A promise that will be resolved with an array of window handles.

code »getCapabilities ( ) ⇒ `!webdriver.promise.Promise`

Returns

A promise that will resolve with the this instance's capabilities.

code »getCurrentUrl ( ) ⇒ `!webdriver.promise.Promise.<string>`

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

Returns

A promise that will be resolved with the current URL.

code »getPageSource ( ) ⇒ `!webdriver.promise.Promise.<string>`

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

A promise that will be resolved with the current page source.

code »getSession ( ) ⇒ `!webdriver.promise.Promise`

Returns

A promise for this client's session.

code »getTitle ( ) ⇒ `!webdriver.promise.Promise.<string>`

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

Returns

A promise that will be resolved with the current page's title.

code »getWindowHandle ( ) ⇒ `!webdriver.promise.Promise.<string>`

Schedules a command to retrieve they current window handle.

Returns

A promise that will be resolved with the current window handle.

code »isElementPresent ( locatorOrElement ) ⇒ `!webdriver.promise.Promise.<boolean>`

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

locatorOrElement: `!(webdriver.Locator|webdriver.By.Hash|Element|Function)`
  The locator to use, or the actual DOM element to be located by the server.

Returns

A promise that will resolve with whether the element is present on the page.

code »manage ( ) ⇒ `!webdriver.WebDriver.Options`

Returns

The options interface for this instance.

code »navigate ( ) ⇒ `!webdriver.WebDriver.Navigation`

Returns

The navigation interface for this instance.

code »quit ( ) ⇒ `!webdriver.promise.Promise.<void>`

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

A promise that will be resolved when the command has completed.

code »`<T>` schedule ( command, description ) ⇒ `!webdriver.promise.Promise.<T>`

Schedules a `webdriver.Command` to be executed by this driver's `webdriver.CommandExecutor`.

Parameters

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

Returns

A promise that will be resolved with the command result.

code »sleep ( ms ) ⇒ `!webdriver.promise.Promise.<void>`

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

Parameters

ms: `number`
  The amount of time, in milliseconds, to sleep.

Returns

A promise that will be resolved when the sleep has finished.

code »switchTo ( ) ⇒ `!webdriver.WebDriver.TargetLocator`

Returns

The target locator interface for this instance.

code »takeScreenshot ( ) ⇒ `!webdriver.promise.Promise.<string>`

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

1. Entire page
2. Current window
3. Visible portion of the current frame
4. The screenshot of the entire display containing the browser

Returns

A promise that will be resolved to the screenshot as a base-64 encoded PNG.

code »wait ( fn, timeout, opt_message ) ⇒ `!webdriver.promise.Promise`

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.

In the event a condition returns a `webdriver.promise.Promise`, the polling loop will wait for it to be resolved and use the resolved value for evaluating whether the condition has been satisfied. The resolution time for a promise is factored into whether a wait has timed out.

Parameters

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

Returns

A promise that will be resolved when the wait condition has been satisfied.

## Instance Properties

code »executor_ : `!webdriver.CommandExecutor`
code »flow_ : `!webdriver.promise.ControlFlow`
code »session_ : `!(webdriver.Session|webdriver.promise.Promise)`

## Static Functions

code »webdriver.WebDriver.acquireSession_ ( executor, command, description, opt_flow ) ⇒ `!webdriver.WebDriver`

Sends a command to the server that is expected to return the details for a `webdriver.Session`. This may either be an existing session, or a newly created one.

Parameters

executor: `!webdriver.CommandExecutor`
  Command executor to use when querying for session details.
command: `!webdriver.Command`
  The command to send to fetch the session details.
description: `string`
  A descriptive debug label for this action.
opt_flow: `webdriver.promise.ControlFlow=`
  The control flow all driver commands should execute under. Defaults to the `currently active` control flow.

Returns

A new WebDriver client for the session.

code »webdriver.WebDriver.attachToSession ( executor, sessionId, opt_flow ) ⇒ `!webdriver.WebDriver`

Creates a new WebDriver client for an existing session.

Parameters

executor: `!webdriver.CommandExecutor`
  Command executor to use when querying for session details.
sessionId: `string`
  ID of the session to attach to.
opt_flow: `webdriver.promise.ControlFlow=`
  The control flow all driver commands should execute under. Defaults to the `currently active` control flow.

Returns

A new client for the specified session.

code »webdriver.WebDriver.createSession ( executor, desiredCapabilities, opt_flow ) ⇒ `!webdriver.WebDriver`

Creates a new WebDriver session.

Parameters

executor: `!webdriver.CommandExecutor`
  The executor to create the new session with.
desiredCapabilities: `!webdriver.Capabilities`
  The desired capabilities for the new session.
opt_flow: `webdriver.promise.ControlFlow=`
  The control flow all driver commands should execute under, including the initial session creation. Defaults to the `currently active` control flow.

Returns

The driver for the newly created session.

code »webdriver.WebDriver.executeCommand_ ( executor, command ) ⇒ `!webdriver.promise.Promise`

Translates a command to its wire-protocol representation before passing it to the given `executor` for execution.

Parameters

executor: `!webdriver.CommandExecutor`
  The executor to use.
command: `!webdriver.Command`
  The command to execute.

Returns

A promise that will resolve with the command response.

code »webdriver.WebDriver.fromWireValue_ ( driver, value ) ⇒ `*`

Converts a value from its JSON representation according to the WebDriver wire protocol. Any JSON object containing a `webdriver.WebElement.ELEMENT_KEY` key will be decoded to a `webdriver.WebElement` object. All other values will be passed through as is.

Parameters

driver: `!webdriver.WebDriver`
  The driver instance to use as the parent of any unwrapped `webdriver.WebElement` values.
value: `*`
  The value to convert.

Returns

The converted value.

code »webdriver.WebDriver.toWireValue_ ( obj ) ⇒ `!webdriver.promise.Promise`

Converts an object to its JSON representation in the WebDriver wire protocol. When converting values of type object, the following steps will be taken:

1. if the object is a WebElement, the return value will be the element's server ID
2. if the object provides a "toJSON" function, the return value of this function will be returned
3. otherwise, the value of each key will be recursively converted according to the rules above.

Parameters

obj: `*`
  The object to convert.

Returns

A promise that will resolve to the input value's JSON representation.