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
Parameters |
---|
|
Classes
|
Instance Methods
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();
webdriver.ActionSequence#perform
is
called. Example:
driver.actions().
mouseDown(element1).
mouseMove(element2).
mouseUp().
perform();
Returns |
---|
|
Schedules a command to execute a custom function.
Parameters |
---|
|
Returns |
|
code »close ( ) ⇒ !webdriver.promise.Promise.<void>
Schedules a command to close the current window.
!webdriver.promise.Promise.<void>
Returns |
---|
|
Returns |
---|
|
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']);
});
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:
webdriver.WebElement
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'); });
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');
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']); });
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
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:
webdriver.WebElement
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.
!webdriver.promise.Promise.<webdriver.WebElement>
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 |
---|
|
Returns |
|
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.
!webdriver.WebElement
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.
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'});
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];
});
}
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 |
---|
|
Returns |
|
code »findElementInternal_ ( locatorFn, context ) ⇒ !webdriver.promise.Promise
!webdriver.promise.Promise
Parameters |
---|
|
Returns |
|
code »findElements ( locator ) ⇒ !webdriver.promise.Promise
Schedule a command to search for multiple elements on the page.
!webdriver.promise.Promise
Parameters |
---|
|
Returns |
|
code »findElementsInternal_ ( locatorFn, context ) ⇒ !webdriver.promise.Promise
!webdriver.promise.Promise
Parameters |
---|
|
Returns |
|
code »get ( url ) ⇒ !webdriver.promise.Promise.<void>
Schedules a command to navigate to the given URL.
!webdriver.promise.Promise.<void>
Parameters |
---|
|
Returns |
|
Schedules a command to retrieve the current list of available window handles.
Returns |
---|
|
Returns |
---|
|
Schedules a command to retrieve the URL of the current page.
Returns |
---|
|
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 |
---|
|
Returns |
---|
|
Schedules a command to retrieve the current page's title.
Returns |
---|
|
Schedules a command to retrieve they current window handle.
Returns |
---|
|
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.
!webdriver.promise.Promise.<boolean>
Parameters |
---|
|
Returns |
|
Returns |
---|
|
Returns |
---|
|
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.
!webdriver.promise.Promise.<void>
Returns |
---|
|
Schedules a webdriver.Command
to be executed by this driver's
webdriver.CommandExecutor
.
webdriver.Command
to be executed by this driver's
webdriver.CommandExecutor
.Parameters |
---|
|
Returns |
|
code »sleep ( ms ) ⇒ !webdriver.promise.Promise.<void>
Schedules a command to make the driver sleep for the given amount of time.
!webdriver.promise.Promise.<void>
Parameters |
---|
|
Returns |
|
Returns |
---|
|
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 |
---|
|
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.
!webdriver.promise.Promise
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.Instance Properties
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.
!webdriver.WebDriver
webdriver.Session
. This may either be an existing session, or a
newly created one.Parameters |
---|
|
Returns |
|
code »webdriver.WebDriver.attachToSession ( executor, sessionId, opt_flow ) ⇒ !webdriver.WebDriver
Creates a new WebDriver client for an existing session.
!webdriver.WebDriver
Parameters |
---|
|
Returns |
|
code »webdriver.WebDriver.createSession ( executor, desiredCapabilities, opt_flow ) ⇒ !webdriver.WebDriver
Creates a new WebDriver session.
!webdriver.WebDriver
Parameters |
---|
|
Returns |
|
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.
!webdriver.promise.Promise
executor
for execution.Parameters |
---|
|
Returns |
|
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.
*
webdriver.WebElement.ELEMENT_KEY
key will be decoded to a
webdriver.WebElement
object. All other values will be passed through
as is.Parameters |
---|
|
Returns |
|
Converts an object to its JSON representation in the WebDriver wire protocol.
When converting values of type object, the following steps will be taken:
- if the object is a WebElement, the return value will be the element's
server ID
- if the object provides a "toJSON" function, the return value of this
function will be returned
- otherwise, the value of each key will be recursively converted according
to the rules above.
Parameters |
---|
|
Returns |
|