Class WebElement

Represents a DOM element. WebElements can be found by searching from the document root using a {@code webdriver.WebDriver} instance, or by searching under another {@code 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'); });

extends

{webdriver.promise.Deferred}

Hierarchy

Index

Constructor methods

Properties

Methods

Constructor methods

constructor(driver: WebDriver, id: Promise): WebElement

constructor

Parameters

  • driver: WebDriver

    The parent WebDriver instance for this element.

  • id: Promise

    Either the opaque ID for the underlying DOM element assigned by the server, or a promise that will resolve to that ID or another WebElement.

Returns

WebElement

constructor(driver: WebDriver, id: string): WebElement

Parameters

Returns

WebElement

Properties

public static ELEMENT_KEY: string

The property key used in the wire protocol to indicate that a JSON object contains the ID of a WebElement.

type

{string}

const

public promise: Promise

The consumer promise for this instance. Provides protected access to the callback registering functions.

type

{!webdriver.promise.Promise}

Methods

public addBoth(callback: (value: any) => any, opt_self?: any): Promise

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.

Parameters

  • callback: (value: any) => any

    The function to call when this promise is either resolved or rejected. The function should expect a single argument: the resolved value or rejection error.

  • opt_self?: any optional

    The object which |this| should refer to when the function is invoked.

Returns

Promise

A new promise which will be resolved with the result of the invoked callback.

public addCallback(callback: (value: any) => any, opt_self?: any): Promise

Registers a function to be invoked when this promise is successfully resolved. This function is provided for backwards compatibility with the Dojo Deferred API.

Parameters

  • callback: (value: any) => any

    The function to call if this promise is successfully resolved. The function should expect a single argument: the promise's resolved value.

  • opt_self?: any optional

    The object which |this| should refer to when the function is invoked.

Returns

Promise

A new promise which will be resolved with the result of the invoked callback.

public addCallbacks(callback: (value: any) => any, errback: (error: any) => any, opt_self?: any): Promise

An alias for {@code 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

  • callback: (value: any) => any

    The function to call if this promise is successfully resolved. The function should expect a single argument: the promise's resolved value.

  • errback: (error: any) => any

    The function to call if this promise is rejected. The function should expect a single argument: the rejection reason.

  • opt_self?: any optional

    The object which |this| should refer to when the function is invoked.

Returns

Promise

A new promise which will be resolved with the result of the invoked callback.

public addErrback(errback: (error: any) => any, opt_self?: any): Promise

Registers a function to be invoked when this promise is rejected. This function is provided for backwards compatibility with the Dojo Deferred API.

Parameters

  • errback: (error: any) => any

    The function to call if this promise is rejected. The function should expect a single argument: the rejection reason.

  • opt_self?: any optional

    The object which |this| should refer to when the function is invoked.

Returns

Promise

A new promise which will be resolved with the result of the invoked callback.

public cancel(opt_reason?: any)

Cancels the computation of this promise's value and flags the promise as a rejected value.

Parameters

  • opt_reason?: any optional

    The reason for cancelling this promise.

public clear(): Promise

Schedules a command to clear the {@code 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

Promise

A promise that will be resolved when the element has been cleared.

public click(): Promise

Schedules a command to click on this element.

Returns

Promise

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

public static equals(a: WebElement, b: WebElement): Promise

Compares to WebElements for equality.

Parameters

Returns

Promise

A promise that will be resolved to whether the two WebElements are equal.

public errback(opt_error?: any)

Parameters

  • opt_error?: any optional

public findElement(locator: Locator, var_args?: Array<any>): WebElement

Schedule a command to find a descendant of this element. 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 = element.findElement(By.id('foo'));
var e2 = element.findElement({id:'foo'});

Note that JS locator searches cannot be restricted to a subtree. All such searches are delegated to this instance's parent WebDriver.

Parameters

  • locator: Locator

    The locator strategy to use when searching for the element.

  • var_args?: Array<any> optional

    Arguments to pass to {@code WebDriver#executeScript} if using a JavaScript locator. Otherwise ignored.

Returns

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.

public findElement(locator: any, var_args?: Array<any>): WebElement

Parameters

  • locator: any
  • var_args?: Array<any> optional

Returns

WebElement

public findElements(locator: Locator, var_args?: Array<any>): Promise

Schedules a command to find all of the descendants of this element that match the given search criteria.

Note that JS locator searches cannot be restricted to a subtree. All such searches are delegated to this instance's parent WebDriver.

Parameters

  • locator: Locator

    The locator strategy to use when searching for the elements.

  • var_args?: Array<any> optional

    Arguments to pass to {@code WebDriver#executeScript} if using a JavaScript locator. Otherwise ignored.

Returns

Promise

A promise that will be resolved with an array of located {@link webdriver.WebElement}s.

public findElements(locator: any, var_args?: Array<any>): Promise

Parameters

  • locator: any
  • var_args?: Array<any> optional

Returns

Promise

public fulfill(opt_value?: any)

Resolves this promise with the given value. If the value is itself a promise and not a reference to this deferred, this instance will wait for it before resolving.

Parameters

  • opt_value?: any optional

    The resolved value.

public getAttribute(attributeName: string): 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. 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 be returned as thus:

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"

Parameters

  • attributeName: string

    The name of the attribute to query.

Returns

Promise

A promise that will be resolved with the attribute's value.

public getCssValue(cssStyleProperty: string): 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.

Parameters

  • cssStyleProperty: string

    The name of the CSS style property to look up.

Returns

Promise

A promise that will be resolved with the requested CSS value.

public getDriver(): WebDriver

Returns

WebDriver

The parent driver for this instance.

public getInnerHtml(): Promise

Schedules a command to retrieve the inner HTML of this element.

Returns

Promise

A promise that will be resolved with the element's inner HTML.

public getLocation(): Promise

Schedules a command to compute the location of this element in page space.

Returns

Promise

A promise that will be resolved to the element's location as a {@code {x:number, y:number}} object.

public getOuterHtml(): Promise

Schedules a command to retrieve the outer HTML of this element.

Returns

Promise

A promise that will be resolved with the element's outer HTML.

public getSize(): Promise

Schedules a command to compute the size of this element's bounding box, in pixels.

Returns

Promise

A promise that will be resolved with the element's size as a {@code {width:number, height:number}} object.

public getTagName(): Promise

Schedules a command to query for the tag/node name of this element.

Returns

Promise

A promise that will be resolved with the element's tag name.

public getText(): Promise

Get the visible (i.e. not hidden by CSS) innerText of this element, including sub-elements, without any leading or trailing whitespace.

Returns

Promise

A promise that will be resolved with the element's visible text.

public isDisplayed(): Promise

Schedules a command to test whether this element is currently displayed.

Returns

Promise

A promise that will be resolved with whether this element is currently visible on the page.

public isElementPresent(locator: Locator, var_args?: Array<any>): Promise

Schedules a command to test if there is at least one descendant of this element that matches the given search criteria.

Note that JS locator searches cannot be restricted to a subtree of the DOM. All such searches are delegated to this instance's parent WebDriver.

Parameters

  • locator: Locator

    The locator strategy to use when searching for the element.

  • var_args?: Array<any> optional

    Arguments to pass to {@code WebDriver#executeScript} if using a JavaScript locator. Otherwise ignored.

Returns

Promise

A promise that will be resolved with whether an element could be located on the page.

public isElementPresent(locator: any, var_args?: Array<any>): Promise

Parameters

  • locator: any
  • var_args?: Array<any> optional

Returns

Promise

public isEnabled(): Promise

Schedules a command to query whether the DOM element represented by this instance is enabled, as dicted by the {@code disabled} attribute.

Returns

Promise

A promise that will be resolved with whether this element is currently enabled.

public isPending(): boolean

Returns

boolean

Whether this promise's value is still being computed.

public isSelected(): Promise

Schedules a command to query whether this element is selected.

Returns

Promise

A promise that will be resolved with whether this element is currently selected.

public reject(opt_error?: any)

Rejects this promise. If the error is itself a promise, this instance will be chained to it and be rejected with the error's resolved value.

Parameters

  • opt_error?: any optional

    The rejection reason, typically either a {@code Error} or a {@code string}.

public removeAll()

Removes all of the listeners previously registered on this deferred.

throws

{Error} If this deferred has already been resolved.

public sendKeys(var_args?: Array<string>): 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 {@code 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.

Parameters

  • var_args?: Array<string> optional

    The sequence of keys to type. All arguments will be joined into a single sequence (var_args is permitted for convenience).

Returns

Promise

A promise that will be resolved when all keys have been typed.

public submit(): Promise

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

Promise

A promise that will be resolved when the form has been submitted.

public then(opt_callback?: (value: any) => any, opt_errback?: (error: any) => any): Promise

Registers listeners for when this instance is resolved. This function most overridden by subtypes.

Parameters

  • opt_callback?: (value: any) => any optional

    The function to call if this promise is successfully resolved. The function should expect a single argument: the promise's resolved value.

  • opt_errback?: (error: any) => any optional

    The function to call if this promise is rejected. The function should expect a single argument: the rejection reason.

Returns

Promise

A new promise which will be resolved with the result of the invoked callback.

public toWireValue(): Promise

see

http://code.google.com/p/selenium/wiki/JsonWireProtocol

Returns

Promise

A promise that resolves to this element's JSON representation as defined by the WebDriver wire protocol.