selenium.element
The remote element handle and its geometry types.
Size
struct Size;
A width and height pair in CSS pixels.
width
long width;
Width in CSS pixels.
height
long height;
Height in CSS pixels.
Position
struct Position;
A viewport coordinate pair in CSS pixels.
x
long x;
Horizontal offset in CSS pixels.
y
long y;
Vertical offset in CSS pixels.
Rect
struct Rect;
A position and size pair in pixels, used for window and element rectangles.
x
long x;
Horizontal offset in pixels.
y
long y;
Vertical offset in pixels.
width
long width;
Width in pixels.
height
long height;
Height in pixels.
Element
class Element;
A handle to a remote element, identified by its W3C element reference.
Every method issues a request against the owning driver's session, so a handle is only valid while that element remains attached to the DOM.
driver
Driver driver;
The driver whose session owns this element.
id
string id;
The opaque W3C element reference returned by the server.
this
this(Driver driver, string id);
Constructs an element handle.
Parameters:
| Name | Description |
|---|---|
Driver driver |
The owning driver session. |
string id |
The W3C element reference. |
text
string text();
The rendered, visible text of the element.
Throws: StaleElementReferenceException if the element is detached. WebDriverException subtypes for connection or server failures. JSONException if the response is not a string.
tagName
string tagName();
The lowercased tag name of the element.
Throws: StaleElementReferenceException if the element is detached. WebDriverException subtypes for connection or server failures. JSONException if the response is not a string.
attribute
string attribute(string name);
The value of the named HTML attribute as it appears in markup.
Parameters:
| Name | Description |
|---|---|
string name |
The attribute name, interpolated into the URL path without encoding. |
Throws: StaleElementReferenceException if the element is detached. WebDriverException subtypes for connection or server failures. JSONException if the response is not a string.
property
string property(string name);
The value of the named live DOM property, which may differ from the markup attribute.
Parameters:
| Name | Description |
|---|---|
string name |
The property name, interpolated into the URL path without encoding. |
Throws: StaleElementReferenceException if the element is detached. WebDriverException subtypes for connection or server failures. JSONException if the response is not a string.
cssValue
string cssValue(string property);
The computed value of the named CSS property.
Parameters:
| Name | Description |
|---|---|
string property |
The CSS property name, interpolated into the URL path without encoding. |
Throws: StaleElementReferenceException if the element is detached. WebDriverException subtypes for connection or server failures. JSONException if the response is not a string.
computedRole
string computedRole();
The computed WAI-ARIA role of the element, or an empty string when none applies.
Support varies by driver; Chromium-based drivers implement the endpoint.
Throws: StaleElementReferenceException if the element is detached. WebDriverException subtypes for connection or server failures. JSONException if the response is not a string.
computedLabel
string computedLabel();
The computed accessible name of the element, or an empty string when none applies.
Support varies by driver; Chromium-based drivers implement the endpoint.
Throws: StaleElementReferenceException if the element is detached. WebDriverException subtypes for connection or server failures. JSONException if the response is not a string.
size
Size size();
The element bounding rectangle as a width and height pair.
Throws: StaleElementReferenceException if the element is detached. WebDriverException subtypes for connection or server failures. JSONException if the response shape is invalid.
position
Position position();
The element bounding rectangle as a top-left coordinate pair.
Throws: StaleElementReferenceException if the element is detached. WebDriverException subtypes for connection or server failures. JSONException if the response shape is invalid.
selected
bool selected();
Whether the element is currently selected, applicable to options and checkable inputs.
Throws: StaleElementReferenceException if the element is detached. WebDriverException subtypes for connection or server failures. JSONException if the response is not a boolean.
enabled
bool enabled();
Whether the element is enabled.
Throws: StaleElementReferenceException if the element is detached. WebDriverException subtypes for connection or server failures. JSONException if the response is not a boolean.
click
void click();
Clicks the element.
Throws: ElementClickInterceptedException if another element intercepts the click. ElementNotInteractableException if the element cannot receive the click. StaleElementReferenceException if the element is detached. InvalidSessionIdException if the session is not active. WebDriverConnectionException if the request fails. WebDriverException subtypes mapped from server errors.
sendKeys
void sendKeys(T...)(T args);
Types the given key sequences into the element.
Each argument is concatenated and dispatched character by character so that
key handlers fire per keystroke. Arguments may be strings of printable
characters or any Key values.
Parameters:
| Name | Description |
|---|---|
T |
One or more string or dchar/Key arguments. |
T args |
The key sequences to type in order. |
Throws: ElementNotInteractableException if the element cannot receive input. InvalidElementStateException if the element is not editable. StaleElementReferenceException if the element is detached. InvalidSessionIdException if the session is not active. WebDriverConnectionException if the request fails. WebDriverException subtypes mapped from server errors.
clear
void clear();
Clears the value of an editable element.
Throws: ElementNotInteractableException if the element cannot receive input. InvalidElementStateException if the element is not editable. StaleElementReferenceException if the element is detached. InvalidSessionIdException if the session is not active. WebDriverConnectionException if the request fails. WebDriverException subtypes mapped from server errors.
screenshot
string screenshot();
A base64 PNG screenshot of the element.
Throws: StaleElementReferenceException if the element is detached. InvalidSessionIdException if the session is not active. WebDriverConnectionException if the request fails. WebDriverException subtypes mapped from server errors. JSONException if the response is not a string.
find
Element find(By by);
Finds the first descendant matching the locator.
Parameters:
| Name | Description |
|---|---|
By by |
The location strategy and selector. |
Returns: A handle to the matched descendant.
Throws: NoSuchElementException if no descendant matches. InvalidSelectorException if the locator is rejected. StaleElementReferenceException if the element is detached. InvalidSessionIdException if the session is not active. WebDriverConnectionException if the request fails. WebDriverException subtypes mapped from server errors.
findAll
Element[] findAll(By by);
Finds every descendant matching the locator.
Parameters:
| Name | Description |
|---|---|
By by |
The location strategy and selector. |
Returns: Handles to all matched descendants, or an empty array if none match.
Throws: InvalidSelectorException if the locator is rejected. StaleElementReferenceException if the element is detached. InvalidSessionIdException if the session is not active. WebDriverConnectionException if the request fails. WebDriverException subtypes mapped from server errors.
shadowRoot
Root shadowRoot();
Returns the shadow root attached to this element.
The returned root has RootState.None.
Chromium and Firefox support this, but Safari is finicky.
Returns: A handle to the shadow root.
Throws: NoSuchShadowRootException if the element does not have a shadow root. DetachedShadowRootException if the shadow root is no longer attached. StaleElementReferenceException if the element is detached. InvalidSessionIdException if the session is not active. WebDriverConnectionException if the request fails. WebDriverException subtypes mapped from server errors.
hasShadowRoot
bool hasShadowRoot();
Whether this element has a shadow root. False if no shadow root or detached.
Returns: True if a shadow root is present.
Throws: StaleElementReferenceException if the element is detached. InvalidSessionIdException if the session is not active. WebDriverConnectionException if the request fails. WebDriverException subtypes mapped from server errors.
toJSON
JSONValue toJSON() const;
Serializes the element into the W3C element reference object.
Returns: The W3C element reference.