Class Index | File Index

Classes


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
 
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.
 
Schedules a command to close the current window.
 
<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.
 
Schedules a command to retrieve the current list of available window handles.
 
 
Returns a promise for one of this driver's capabilities.
 
Schedules a command to retrieve the URL of the current page.
 
Schedules a command to retrieve the current page's source.
 
 
Schedules a command to retrieve the current page's title.
 
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.
 
 
 
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.
 
 
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: 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:
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:
  1. Entire page
  2. Current window
  3. Visible portion of the current frame
  4. 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.

Documentation generated by JsDoc Toolkit 2.4.0 on Sat Jan 25 2014 14:42:03 GMT-0500 (EST)