Class webdriver.WebElement
code »webdriver.promise.Promise
└ webdriver.promise.Deferred
└ webdriver.WebElement
Represents a DOM element. WebElements can be found by searching from the
document root using a webdriver.WebDriver
instance, or by searching
under another webdriver.WebElement
:
driver.get('http://www.google.com');
var searchForm = driver.findElement(By.tagName('form'));
var searchBox = searchForm.findElement(By.name('q'));
searchBox.sendKeys('webdriver');
The WebElement is implemented as a promise for compatibility with the promise
API. It will always resolve itself when its internal state has been fully
resolved and commands may be issued against the element. This can be used to
catch errors when an element cannot be located on the page:
driver.findElement(By.id('not-there')).then(function(element) {
alert('Found an element that was not expected to be there!');
}, function(error) {
alert('The element was not found, as expected');
});
Constructor
Parameters |
---|
|
Instance Methods
Defined in webdriver.WebElement
Schedules a command to clear the value
of this element. This command
has no effect if the underlying DOM element is neither a text INPUT element
nor a TEXTAREA element.
value
of this element. This command
has no effect if the underlying DOM element is neither a text INPUT element
nor a TEXTAREA element.Returns |
---|
|
Schedules a command to click on this element.
Returns |
---|
|
code »findElement ( locator ) ⇒ !webdriver.WebElement
Schedule a command to find a descendant of this element. 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 = element.findElement(By.id('foo'));
var e2 = element.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 = element.findElement(firstVisibleLink);
function firstVisibleLink(element) {
var links = element.findElements(By.tagName('a'));
return webdriver.promise.filter(links, function(link) {
return links.isDisplayed();
}).then(function(visibleLinks) {
return visibleLinks[0];
});
}
!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 = element.findElement(By.id('foo'));
var e2 = element.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 = element.findElement(firstVisibleLink);
function firstVisibleLink(element) {
var links = element.findElements(By.tagName('a'));
return webdriver.promise.filter(links, function(link) {
return links.isDisplayed();
}).then(function(visibleLinks) {
return visibleLinks[0];
});
}
Parameters |
---|
|
Returns |
|
code »findElements ( locator ) ⇒ !webdriver.promise.Promise
Schedules a command to find all of the descendants of this element that
match the given search criteria.
!webdriver.promise.Promise
Parameters |
---|
|
Returns |
|
code »getAttribute ( attributeName ) ⇒ !webdriver.promise.Promise
Schedules a command to query for the value of the given attribute of the
element. Will return the current value, even if it has been modified after
the page has been loaded. More exactly, this method will return the value of
the given attribute, unless that attribute is not present, in which case the
value of the property with the same name is returned. If neither value is
set, null is returned (for example, the "value" property of a textarea
element). The "style" attribute is converted as best can be to a
text representation with a trailing semi-colon. The following are deemed to
be "boolean" attributes and will return either "true" or null:
async, autofocus, autoplay, checked, compact, complete, controls, declare,
defaultchecked, defaultselected, defer, disabled, draggable, ended,
formnovalidate, hidden, indeterminate, iscontenteditable, ismap, itemscope,
loop, multiple, muted, nohref, noresize, noshade, novalidate, nowrap, open,
paused, pubdate, readonly, required, reversed, scoped, seamless, seeking,
selected, spellcheck, truespeed, willvalidate
Finally, the following commonly mis-capitalized attribute/property names
are evaluated as expected:
- "class"
- "readonly"
!webdriver.promise.Promise
Parameters |
---|
|
Returns |
|
code »getCssValue ( cssStyleProperty ) ⇒ !webdriver.promise.Promise
Schedules a command to query for the computed style of the element
represented by this instance. If the element inherits the named style from
its parent, the parent will be queried for its value. Where possible, color
values will be converted to their hex representation (e.g. #00ff00 instead of
rgb(0, 255, 0)).
Warning: the value returned will be as the browser interprets it, so
it may be tricky to form a proper assertion.
!webdriver.promise.Promise
Parameters |
---|
|
Returns |
|
Returns |
---|
|
Schedules a command to retrieve the inner HTML of this element.
Returns |
---|
|
Schedules a command to compute the location of this element in page space.
Returns |
---|
{x:number, y:number} object. |
Schedules a command to retrieve the outer HTML of this element.
Returns |
---|
|
Schedules a command to compute the size of this element's bounding box, in
pixels.
Returns |
---|
{width:number, height:number} object. |
Schedules a command to query for the tag/node name of this element.
Returns |
---|
|
Get the visible (i.e. not hidden by CSS) innerText of this element, including
sub-elements, without any leading or trailing whitespace.
Returns |
---|
|
Schedules a command to test whether this element is currently displayed.
Returns |
---|
|
code »isElementPresent ( locator ) ⇒ !webdriver.promise.Promise.<boolean>
Schedules a command to test if there is at least one descendant of this
element that matches the given search criteria.
!webdriver.promise.Promise.<boolean>
Parameters |
---|
|
Returns |
|
Schedules a command to query whether the DOM element represented by this
instance is enabled, as dicted by the disabled
attribute.
disabled
attribute.Returns |
---|
|
Schedules a command to query whether this element is selected.
Returns |
---|
|
code »schedule_ ( command, description ) ⇒ !webdriver.promise.Promise
Schedules a command that targets this element with the parent WebDriver
instance. Will ensure this element's ID is included in the command parameters
under the "id" key.
!webdriver.promise.Promise
Parameters |
---|
|
Returns |
|
code »sendKeys ( var_args ) ⇒ !webdriver.promise.Promise
Schedules a command to type a sequence on the DOM element represented by this
instance.
Modifier keys (SHIFT, CONTROL, ALT, META) are stateful; once a modifier is
processed in the keysequence, that key state is toggled until one of the
following occurs:
- The modifier key is encountered again in the sequence. At this point the
state of the key is toggled (along with the appropriate keyup/down events).
- The
webdriver.Key.NULL
key is encountered in the sequence. When
this key is encountered, all modifier keys current in the down state are
released (with accompanying keyup events). The NULL key can be used to
simulate common keyboard shortcuts:
element.sendKeys("text was",
webdriver.Key.CONTROL, "a", webdriver.Key.NULL,
"now text is");
// Alternatively:
element.sendKeys("text was",
webdriver.Key.chord(webdriver.Key.CONTROL, "a"),
"now text is");
- The end of the keysequence is encountered. When there are no more keys
to type, all depressed modifier keys are released (with accompanying keyup
events).
Note: On browsers where native keyboard events are not yet
supported (e.g. Firefox on OS X), key events will be synthesized. Special
punctionation keys will be synthesized according to a standard QWERTY en-us
keyboard layout.
!webdriver.promise.Promise
webdriver.Key.NULL
key is encountered in the sequence. When
this key is encountered, all modifier keys current in the down state are
released (with accompanying keyup events). The NULL key can be used to
simulate common keyboard shortcuts:
element.sendKeys("text was",
webdriver.Key.CONTROL, "a", webdriver.Key.NULL,
"now text is");
// Alternatively:
element.sendKeys("text was",
webdriver.Key.chord(webdriver.Key.CONTROL, "a"),
"now text is");
Parameters |
---|
|
Returns |
|
Schedules a command to submit the form containing this element (or this
element if it is a FORM element). This command is a no-op if the element is
not contained in a form.
Returns |
---|
|
Returns |
---|
|
Defined in webdriver.promise.Deferred
Defined in webdriver.promise.Promise
code »addBoth ( callback, opt_self ) ⇒ !webdriver.promise.Promise
Deprecated: Use #thenFinally()
instead.Registers a function to be invoked when this promise is either rejected or
resolved. This function is provided for backwards compatibility with the
Dojo Deferred API.
!webdriver.promise.Promise
#thenFinally()
instead.Parameters |
---|
Returns |
|
code »addCallback ( callback, opt_self ) ⇒ !webdriver.promise.Promise
Deprecated: Use #then()
instead.Registers a function to be invoked when this promise is successfully
resolved. This function is provided for backwards compatibility with the
Dojo Deferred API.
!webdriver.promise.Promise
#then()
instead.Parameters |
---|
Returns |
|
code »addCallbacks ( callback, errback, opt_self ) ⇒ !webdriver.promise.Promise
Deprecated: Use #then()
instead.An alias for webdriver.promise.Promise.prototype.then
that permits
the scope of the invoked function to be specified. This function is provided
for backwards compatibility with the Dojo Deferred API.
!webdriver.promise.Promise
#then()
instead.webdriver.promise.Promise.prototype.then
that permits
the scope of the invoked function to be specified. This function is provided
for backwards compatibility with the Dojo Deferred API.Parameters |
---|
|
Returns |
|
code »addErrback ( errback, opt_self ) ⇒ !webdriver.promise.Promise
Deprecated: Use #thenCatch()
instead.Registers a function to be invoked when this promise is rejected.
This function is provided for backwards compatibility with the
Dojo Deferred API.
!webdriver.promise.Promise
#thenCatch()
instead.Parameters |
---|
Returns |
|
code »then ( opt_callback, opt_errback ) ⇒ !webdriver.promise.Promise
Registers listeners for when this instance is resolved. This function most
overridden by subtypes.
!webdriver.promise.Promise
Parameters |
---|
|
Returns |
|
code »thenCatch ( errback ) ⇒ !webdriver.promise.Promise
Registers a listener for when this promise is rejected. This is synonymous
with the catch
clause in a synchronous API:
// Synchronous API:
try {
doSynchronousWork();
} catch (ex) {
console.error(ex);
}
// Asynchronous promise API:
doAsynchronousWork().thenCatch(function(ex) {
console.error(ex);
});
!webdriver.promise.Promise
catch
clause in a synchronous API:
// Synchronous API:
try {
doSynchronousWork();
} catch (ex) {
console.error(ex);
}
// Asynchronous promise API:
doAsynchronousWork().thenCatch(function(ex) {
console.error(ex);
});
Parameters |
---|
|
Returns |
|
code »thenFinally ( callback ) ⇒ !webdriver.promise.Promise
Registers a listener to invoke when this promise is resolved, regardless
of whether the promise's value was successfully computed. This function
is synonymous with the finally
clause in a synchronous API:
// Synchronous API:
try {
doSynchronousWork();
} finally {
cleanUp();
}
// Asynchronous promise API:
doAsynchronousWork().thenFinally(cleanUp);
Note: similar to the finally
clause, if the registered
callback returns a rejected promise or throws an error, it will silently
replace the rejection error (if any) from this promise:
try {
throw Error('one');
} finally {
throw Error('two'); // Hides Error: one
}
webdriver.promise.rejected(Error('one'))
.thenFinally(function() {
throw Error('two'); // Hides Error: one
});
!webdriver.promise.Promise
finally
clause in a synchronous API:
// Synchronous API:
try {
doSynchronousWork();
} finally {
cleanUp();
}
// Asynchronous promise API:
doAsynchronousWork().thenFinally(cleanUp);
try {
throw Error('one');
} finally {
throw Error('two'); // Hides Error: one
}
webdriver.promise.rejected(Error('one'))
.thenFinally(function() {
throw Error('two'); // Hides Error: one
});
Parameters |
---|
|
Instance Properties
Defined in webdriver.WebElement
The parent WebDriver instance for this element.
A promise that resolves to the JSON representation of this WebElement's
ID, as defined by the WebDriver wire protocol.
Defined in webdriver.promise.Deferred
Represents the eventual value of a completed operation. Each promise may be
in one of three states: pending, resolved, or rejected. Each promise starts
in the pending state and may make a single transition to either a
fulfilled or failed state.
This class is based on the Promise/A proposal from CommonJS. Additional
functions are provided for API compatibility with Dojo Deferred objects.
Static Functions
Compares to WebElements for equality.
Parameters |
---|
|
Returns |
|