Elements

An Element is a session-scoped handle to a DOM node. Every operation sends a WebDriver command through the owning Driver. If the node is detached, commands can throw StaleElementReferenceException.

For upstream concepts, see the official Selenium element documentation.

Locators

By pairs a W3C location strategy with a selector. It is declared in selenium.locator and re-exported by the selenium package. The current helpers are:

Helper	Strategy
`By.css(selector)`	CSS selector.
`By.xpath(expression)`	XPath expression.
`By.tagName(name)`	Tag name.
`By.linkText(text)`	Anchor with exact visible text.
`By.partialLinkText(text)`	Anchor containing the text.

There is no By.id helper. Use a CSS ID selector such as By.css("#submit").

Element button = driver.find(By.css("#submit"));
Element[] links = driver.findAll(By.tagName("a"));

find throws NoSuchElementException when no element matches. findAll returns an empty array.

State and Geometry

Member	Purpose
`text`	Rendered visible text.
`tagName`	Lowercased tag name.
`attribute(name)`	HTML attribute value.
`property(name)`	Live DOM property value.
`cssValue(name)`	Computed CSS value.
`size`	Width and height as `Size`.
`position`	Top-left coordinates as `Position`.
`selected`	Whether an option or checkable input is selected.
`enabled`	Whether the element is enabled.
`computedRole`	Computed WAI-ARIA role.
`computedLabel`	Computed accessible name.
`screenshot`	Base64 PNG of the element.

Element input = driver.find(By.css("input[name='username']"));

writeln(input.attribute("placeholder"));
writeln(input.property("value"));
writeln(input.enabled);
writeln(input.size.width);

Computed Accessibility

computedRole and computedLabel expose the W3C computed accessibility values for an element. computedRole returns the WAI-ARIA role the browser applies, and computedLabel returns the accessible name. Both return an empty string when no role or name applies. Support varies by driver but Chromium-based drivers implement these endpoints.

Element button = driver.find(By.css("#save"));
writeln(button.computedRole);
writeln(button.computedLabel);

Interaction

Member	Purpose
`click()`	Click the element.
`sendKeys(text...)`	Concatenate and type one or more strings character by character.
`clear()`	Clear an editable element.

Element form = driver.find(By.tagName("form"));
Element input = form.find(By.css("input[name='username']"));

input.clear();
input.sendKeys("alice");
form.find(By.css("button[type='submit']")).click();

Descendant Search

Calling find or findAll on an element restricts the search to its descendants:

Element table = driver.find(By.css("#data"));
Element[] rows = table.findAll(By.tagName("tr"));
Element firstCell = table.find(By.tagName("td"));

Descendant searches use the current session timeout configured through driver.timeouts.implicit.

Shadow Roots

element.shadowRoot requests the element's W3C shadow-root reference. It throws NoSuchShadowRootException when no shadow root exists. The returned Root supports find and findAll through the W3C shadow endpoints.

Element host = driver.find(By.css("my-component"));
Root shadow = host.shadowRoot;
Element button = shadow.find(By.css("button"));

ChromeDriver and geckodriver return and search closed shadow roots through this endpoint, even though page JavaScript cannot read host.shadowRoot for a closed root. Safari does not expose closed roots through /shadow and raises NoSuchShadowRootException.

Only open shadow roots can be discovered by driver.roots, because it walks the page through JavaScript.

Serialization

element.toJSON() returns the W3C element-reference object required when passing the element to commands such as frame switching. Reference IDs are opaque and valid only within the owning session.