`selenium.root`

Root abstractions for the primary document, iframes, and shadow roots.

`RootType`

enum RootType: string;

The kind of root represented by a Root handle.

`Primary`

Primary

The top-level document root.

`Embedded`

Embedded

An iframe element root.

`Shadow`

Shadow

A shadow-root root.

`RootState`

enum RootState: uint;

The lifecycle and accessibility state of a Root.

Readiness flags (Uninitialized through Complete) describe the state.

Open and Closed are shadow-root mode flags. A shadow root therefore carries one readiness bit ORed with its mode bit.

Loaded is reserved for a distinct loaded state but is not currently produced by Driver.roots, and Closed is (usually) undiscoverable through Driver.roots because closed shadow roots have no shadowRoot property.

`None`

None

No state flags are set.

`Uninitialized`

Uninitialized

The document has not started loading, or its state could not be read.

`Loading`

Loading

The document is still loading.

`Loaded`

Loaded

Reserved for a loaded document state.

`Interactive`

Interactive

The document has parsed and is interactive, but subresources may still load.

`Complete`

Complete

The document and its subresources have finished loading.

`Open`

Open

The shadow root is open and accessible through element.shadowRoot.

`Closed`

Closed

The shadow root is closed.

`Root`

class Root;

A handle to a searchable root context within the DOM.

Primary represents the top-level document, Embedded represents an iframe element, and Shadow represents a shadow root. Only find and findAll are supported, matching the subset of W3C commands valid on shadow roots.

`driver`

Driver driver;

The driver whose session owns this root.

`id`

string id;

The opaque W3C reference. For Primary this is empty.

`this`

this(Driver driver, string id, RootType type, RootState state);

Constructs a root handle.

Parameters:

Name	Description
`Driver driver`	The owning driver session.
`string id`	The W3C element or shadow root reference.
`RootType type`	The kind of root.
`RootState state`	The current state bitmask.

`type`

RootType type();

The root type.

`state`

RootState state();

The root state bitmask. See RootState for details.

`find`

Element find(By by);

Finds the first element matching the locator within this root.

For Embedded roots the current frame is switched to the iframe before searching. For Primary roots the frame is reset to the top-level first. The driver remains in the resulting context after the call.

Parameters:

Name	Description
`By by`	The location strategy and selector.

Returns: A handle to the matched element.

Throws: NoSuchElementException if no element matches. WebDriverException subtypes for other server or connection failures.

`findAll`

Element[] findAll(By by);

Finds every element matching the locator within this root.

For Embedded roots the current frame is switched to the iframe before searching. For Primary roots the frame is reset to the top-level first. The driver remains in the resulting context after the call.

Parameters:

Name	Description
`By by`	The location strategy and selector.

Returns: Handles to all matched elements, or an empty array if none match.

Throws: WebDriverException subtypes for selector, frame, session, or connection failures.

`toJSON`

JSONValue toJSON() const;

Serializes the root into the appropriate W3C reference object.

Primary roots serialize to an empty object.

Returns: The W3C element, shadow-root reference, or empty object if primary.