element module

element.Store

class element.Store()

Stores known/seen elements and their associated web element references.

Elements are added by calling {@link #add()} or {@link addAll()}, and may be queried by their web element reference using {@link get()}.

element.Store.add(el)

Make an element seen.

Arguments:
  • el (Element|WindowProxy|XULElement) – Element to add to set of seen elements.
Throws:

TypeError – If <var>el</var> is not an {@link Element} or a {@link XULElement}.

Returns:

WebElement – Web element reference associated with element.

element.Store.addAll(els)

Make a collection of elements seen.

The oder of the returned web element references is guaranteed to match that of the collection passed in.

Arguments:
  • els (NodeList) – Sequence of elements to add to set of seen elements.
Returns:

Array.<WebElement> – List of the web element references associated with each element from <var>els</var>.

element.Store.get(webEl, win)

Retrieve a DOM {@link Element} or a {@link XULElement} by its unique {@link WebElement} reference.

Arguments:
  • webEl (WebElement) – Web element reference to find the associated {@link Element} of.
  • win (WindowProxy) – Current browsing context, which may differ from the associate browsing context of <var>el</var>.
Throws:
  • TypeError – If <var>webEl</var> is not a {@link WebElement}.
  • NoSuchElementError – If the web element reference <var>uuid</var> has not been seen before.
  • StaleElementReferenceError – If the element has gone stale, indicating it is no longer attached to the DOM, or its node document is no longer the active document.
Returns:

Element|XULElement – Element associated with reference.

element.Store.has(webEl)

Determine if the provided web element reference has been seen before/is in the element store.

Unlike when getting the element, a staleness check is not performed.

Arguments:
  • webEl (WebElement) – Element’s associated web element reference.
Throws:

TypeError – If <var>webEl</var> is not a {@link WebElement}.

Returns:

boolean – True if element is in the store, false otherwise.

element.find

element.find(container, strategy, selector, opts)

Find a single element or a collection of elements starting at the document root or a given node.

If |timeout| is above 0, an implicit search technique is used. This will wait for the duration of <var>timeout</var> for the element to appear in the DOM.

See the {@link element.Strategy} enum for a full list of supported search strategies that can be passed to <var>strategy</var>.

Available flags for <var>opts</var>:

<dl>

<dt><code>all</code> <dd>

If true, a multi-element search selector is used and a sequence of elements will be returned. Otherwise a single element.

<dt><code>timeout</code> <dd>

Duration to wait before timing out the search. If <code>all</code> is false, a {@link NoSuchElementError} is thrown if unable to find the element within the timeout duration.

<dt><code>startNode</code> <dd>Element to use as the root of the search.

Arguments:
  • WindowProxy> container (Object.<string,) – Window object and an optional shadow root that contains the root shadow DOM element.
  • strategy (string) – Search strategy whereby to locate the element(s).
  • selector (string) – Selector search pattern. The selector must be compatible with the chosen search <var>strategy</var>.
  • ?> opts (Object.<string,) – Options.
Throws:

InvalidSelectorError If <var>strategy</var> is unknown.

Throws:

InvalidSelectorError If <var>selector</var> is malformed.

Throws:

NoSuchElementError If a single element is requested, this error will throw if the element is not found.

Returns:

Promise.<(Element|Array.<Element>)> – Single element or a sequence of elements.

element.findByXPath

element.findByXPath(document, startNode, expression)

Find a single element by XPath expression.

Arguments:
  • document (HTMLDocument) – Document root.
  • startNode (Element) – Where in the DOM hiearchy to begin searching.
  • expression (string) – XPath search expression.
Returns:

Node – First element matching <var>expression</var>.

element.findByXPathAll

element.findByXPathAll(document, startNode, expression)

Find elements by XPath expression.

Arguments:
  • document (HTMLDocument) – Document root.
  • startNode (Element) – Where in the DOM hierarchy to begin searching.
  • expression (string) – XPath search expression.
Returns:

Iterable.<Node> – Iterator over elements matching <var>expression</var>.

element.findByLinkText

element.findByLinkText(startNode, linkText)

Find all hyperlinks descendant of <var>startNode</var> which link text is <var>linkText</var>.

Arguments:
  • startNode (Element) – Where in the DOM hierarchy to begin searching.
  • linkText (string) – Link text to search for.
Returns:

Iterable.<HTMLAnchorElement> – Sequence of link elements which text is <var>s</var>.

element.findByPartialLinkText

element.findByPartialLinkText(startNode, linkText)

Find all hyperlinks descendant of <var>startNode</var> which link text contains <var>linkText</var>.

Arguments:
  • startNode (Element) – Where in the DOM hierachy to begin searching.
  • linkText (string) – Link text to search for.
Returns:

Iterable.<HTMLAnchorElement> – Iterator of link elements which text containins <var>linkText</var>.

element.findAnonymousNodes

element.findAnonymousNodes(document, node)

Find anonymous nodes of <var>node</var>.

Arguments:
  • document (XULDocument) – Root node of the document.
  • node (XULElement) – Where in the DOM hierarchy to begin searching.
Returns:

Iterable.<XULElement> – Iterator over anonymous elements.

element.findClosest

element.findClosest(startNode, selector)

Finds the closest parent node of <var>startNode</var> by CSS a <var>selector</var> expression.

Arguments:
  • startNode (Node) – Cyce through <var>startNode</var>’s parent nodes in tree-order and return the first match to <var>selector</var>.
  • selector (string) – CSS selector expression.
Returns:

Node – First match to <var>selector</var>, or null if no match was found.

element.isCollection

element.isCollection(seq)

Determines if <var>obj<var> is an HTML or JS collection.

Arguments:
  • seq (*) – Type to determine.
Returns:

boolean – True if <var>seq</va> is collection.

element.isStale

element.isStale(el, win)

Determines if <var>el</var> is stale.

A stale element is an element no longer attached to the DOM or which node document is not the active document of the current browsing context.

The currently selected browsing context, specified through <var>window<var>, is a WebDriver concept defining the target against which commands will run. As the current browsing context may differ from <var>el</var>’s associated context, an element is considered stale even if it is connected to a living (not discarded) browsing context such as an <tt>&lt;iframe&gt;</tt>.

Arguments:
  • el (Element) – DOM element to check for staleness. If null, which may be the case if the element has been unwrapped from a weak reference, it is always considered stale.
  • win (WindowProxy) – Current browsing context, which may differ from the associate browsing context of <var>el</var>. When retrieving XUL elements, this is optional.
Returns:

boolean – True if <var>el</var> is stale, false otherwise.

element.isSelected

element.isSelected(el)

Determine if <var>el</var> is selected or not.

This operation only makes sense on <tt>&lt;input type=checkbox&gt;</tt>, <tt>&lt;input type=radio&gt;</tt>, and <tt>&gt;option&gt;</tt> elements.

Arguments:
  • el (DOMElement|XULElement) – Element to test if selected.
Returns:

boolean – True if element is selected, false otherwise.

element.isReadOnly

element.isReadOnly(el)

An element is considered read only if it is an <code>&lt;input&gt;</code> or <code>&lt;textarea&gt;</code> element whose <code>readOnly</code> content IDL attribute is set.

Arguments:
  • el (Element) – Element to test is read only.
Returns:

boolean – True if element is read only.

element.isDisabled

element.isDisabled(el)

An element is considered disabled if it is a an element that can be disabled, or it belongs to a container group which <code>disabled</code> content IDL attribute affects it.

Arguments:
  • el (Element) – Element to test for disabledness.
Returns:

boolean – True if element, or its container group, is disabled.

element.isMutableFormControl

element.isMutableFormControl(el)

Denotes elements that can be used for typing and clearing.

Elements that are considered WebDriver-editable are non-readonly and non-disabled <code>&lt;input&gt;</code> elements in the Text, Search, URL, Telephone, Email, Password, Date, Month, Date and Time Local, Number, Range, Color, and File Upload states, and <code>&lt;textarea&gt;</code> elements.

Arguments:
  • el (Element) – Element to test.
Returns:

boolean – True if editable, false otherwise.

element.isEditingHost

element.isEditingHost(el)

An editing host is a node that is either an HTML element with a <code>contenteditable</code> attribute, or the HTML element child of a document whose <code>designMode</code> is enabled.

Arguments:
  • el (Element) – Element to determine if is an editing host.
Returns:

boolean – True if editing host, false otherwise.

element.isEditable

element.isEditable(el)

Determines if an element is editable according to WebDriver.

An element is considered editable if it is not read-only or disabled, and one of the following conditions are met:

<ul> <li>It is a <code>&lt;textarea&gt;</code> element.

<li>It is an <code>&lt;input&gt;</code> element that is not of the <code>checkbox</code>, <code>radio</code>, <code>hidden</code>, <code>submit</code>, <code>button</code>, or <code>image</code> types.

<li>It is content-editable.

<li>It belongs to a document in design mode. </ul>

Arguments:
  • Element (Element) – to test if editable.
Returns:

boolean – True if editable, false otherwise.

element.coordinates

element.coordinates(node, xOffset, yOffset)

This function generates a pair of coordinates relative to the viewport given a target element and coordinates relative to that element’s top-left corner.

Arguments:
  • node (Node) – Target node.
  • xOffset (number) – Horizontal offset relative to target’s top-left corner. Defaults to the centre of the target’s bounding box.
  • yOffset (number) – Vertical offset relative to target’s top-left corner. Defaults to the centre of the target’s bounding box.
Throws:

TypeError If <var>xOffset</var> or <var>yOffset</var> are not numbers.

Returns:

Object.<string, number> – X- and Y coordinates.

element.inViewport

element.inViewport(el, x, y)

This function returns true if the node is in the viewport.

Arguments:
  • el (Element) – Target element.
  • x (number) – Horizontal offset relative to target. Defaults to the centre of the target’s bounding box.
  • y (number) – Vertical offset relative to target. Defaults to the centre of the target’s bounding box.
Returns:

boolean – True if if <var>el</var> is in viewport, false otherwise.

element.getContainer

element.getContainer(el)

Gets the element’s container element.

An element container is defined by the WebDriver specification to be an <tt>&lt;option&gt;</tt> element in a <a href=”https://html.spec.whatwg.org/#concept-element-contexts”>valid element context</a>, meaning that it has an ancestral element that is either <tt>&lt;datalist&gt;</tt> or <tt>&lt;select&gt;</tt>.

If the element does not have a valid context, its container element is itself.

Arguments:
  • el (Element) – Element to get the container of.
Returns:

Element – Container element of <var>el</var>.

element.isInView

element.isInView(el)

An element is in view if it is a member of its own pointer-interactable paint tree.

This means an element is considered to be in view, but not necessarily pointer-interactable, if it is found somewhere in the <code>elementsFromPoint</code> list at <var>el</var>’s in-view centre coordinates.

Before running the check, we change <var>el</var>’s pointerEvents style property to “auto”, since elements without pointer events enabled do not turn up in the paint tree we get from document.elementsFromPoint. This is a specialisation that is only relevant when checking if the element is in view.

Arguments:
  • el (Element) – Element to check if is in view.
Returns:

boolean – True if <var>el</var> is inside the viewport, or false otherwise.

element.isVisible

element.isVisible(el, x, y)

This function throws the visibility of the element error if the element is not displayed or the given coordinates are not within the viewport.

Arguments:
  • el (Element) – Element to check if visible.
  • x (number) – Horizontal offset relative to target. Defaults to the centre of the target’s bounding box.
  • y (number) – Vertical offset relative to target. Defaults to the centre of the target’s bounding box.
Returns:

boolean – True if visible, false otherwise.

element.isObscured

element.isObscured(el)

A pointer-interactable element is defined to be the first non-transparent element, defined by the paint order found at the centre point of its rectangle that is inside the viewport, excluding the size of any rendered scrollbars.

An element is obscured if the pointer-interactable paint tree at its centre point is empty, or the first element in this tree is not an inclusive descendant of itself.

Arguments:
  • el (DOMElement) – Element determine if is pointer-interactable.
Returns:

boolean – True if element is obscured, false otherwise.

element.getInViewCentrePoint

element.getInViewCentrePoint(rect, win)

Calculate the in-view centre point of the area of the given DOM client rectangle that is inside the viewport.

Arguments:
  • rect (DOMRect) – Element off a DOMRect sequence produced by calling <code>getClientRects</code> on an {@link Element}.
  • win (WindowProxy) – Current window global.
Returns:

Map.<string, number> – X and Y coordinates that denotes the in-view centre point of <var>rect</var>.

element.getPointerInteractablePaintTree

element.getPointerInteractablePaintTree(el)

Produces a pointer-interactable elements tree from a given element.

The tree is defined by the paint order found at the centre point of the element’s rectangle that is inside the viewport, excluding the size of any rendered scrollbars.

Arguments:
  • el (DOMElement) – Element to determine if is pointer-interactable.
Returns:

Array.<DOMElement> – Sequence of elements in paint order.

element.scrollIntoView

element.scrollIntoView(el)

Attempts to scroll into view |el|.

Arguments:
  • el (DOMElement) – Element to scroll into view.

element.isElement

element.isElement(node)

Ascertains whether <var>node</var> is a DOM-, SVG-, or XUL element.

Arguments:
  • node (*) – Element thought to be an <code>Element</code> or <code>XULElement</code>.
Returns:

boolean – True if <var>node</var> is an element, false otherwise.

element.isDOMElement

element.isDOMElement(node)

Ascertains whether <var>node</var> is a DOM element.

Arguments:
  • node (*) – Element thought to be an <code>Element</code>.
Returns:

boolean – True if <var>node</var> is a DOM element, false otherwise.

element.isXULElement

element.isXULElement(node)

Ascertains whether <var>el</var> is a XUL- or XBL element.

Arguments:
  • node (*) – Element thought to be a XUL- or XBL element.
Returns:

boolean – True if <var>node</var> is a XULElement or XBLElement, false otherwise.

element.isDOMWindow

element.isDOMWindow(node)

Ascertains whether <var>node</var> is a <code>WindowProxy</code>.

Arguments:
  • node (*) – Node thought to be a <code>WindowProxy</code>.
Returns:

boolean – True if <var>node</var> is a DOM window.

element.isBooleanAttribute

element.isBooleanAttribute(el, attr)

Tests if the attribute is a boolean attribute on element.

Arguments:
  • el (DOMElement) – Element to test if <var>attr</var> is a boolean attribute on.
  • attr (string) – Attribute to test is a boolean attribute.
Returns:

boolean – True if the attribute is boolean, false otherwise.

ChromeWebElement

class ChromeWebElement()

XUL elements in chrome space are represented as chrome web elements over the wire protocol.

ContentWebElement

class ContentWebElement()

DOM elements are represented as web elements when they are transported over the wire protocol.

ContentWebFrame

class ContentWebFrame()

Nested browsing contexts, such as the <code>WindowProxy</code> associated with <tt>&lt;frame&gt;</tt> and <tt>&lt;iframe&gt;</tt>, are represented as web frames over the wire protocol.

ContentWebWindow

class ContentWebWindow()

Top-level browsing contexts, such as <code>WindowProxy</code> whose <code>opener</code> is null, are represented as web windows over the wire protocol.

WebElement

class WebElement(uuid)

A web element is an abstraction used to identify an element when it is transported via the protocol, between remote- and local ends.

In Marionette this abstraction can represent DOM elements, WindowProxies, and XUL elements.

Arguments:
  • uuid (string) – Identifier that must be unique across all browsing contexts for the contract to be upheld.
WebElement.from(node)

Returns a new {@link WebElement} reference for a DOM element, <code>WindowProxy</code>, or XUL element.

Arguments:
  • node (Element|WindowProxy|XULElement) – Node to construct a web element reference for.
Throws:

InvalidArgumentError – If <var>node</var> is neither a <code>WindowProxy</code>, DOM element, or a XUL element.

Returns:

ContentWebElement|ChromeWebElement – Web element reference for <var>el</var>.

WebElement.fromJSON(json)

Unmarshals a JSON Object to one of {@link ContentWebElement}, {@link ContentWebWindow}, {@link ContentWebFrame}, or {@link ChromeWebElement}.

Arguments:
  • string> json (Object.<string,) – Web element reference, which is supposed to be a JSON Object where the key is one of the {@link WebElement} concrete classes’ UUID identifiers.
Throws:

InvalidArgumentError – If <var>json</var> is not a web element reference.

Returns:

WebElement – Representation of the web element.

WebElement.fromUUID(uuid, context)

Constructs a {@link ContentWebElement} or {@link ChromeWebElement} from a a string <var>uuid</var>.

This whole function is a workaround for the fact that clients to Marionette occasionally pass <code>{id: <uuid>}</code> JSON Objects instead of web element representations. For that reason we need the <var>context</var> argument to determine what kind of {@link WebElement} to return.

Arguments:
  • uuid (string) – UUID to be associated with the web element.
  • context (Context) – Context, which is used to determine if the returned type should be a content web element or a chrome web element.
Throws:

InvalidArgumentError – If <var>uuid</var> is not a string or <var>context</var> is an invalid context.

Returns:

WebElement – One of {@link ContentWebElement} or {@link ChromeWebElement}, based on <var>context</var>.

WebElement.generateUUID()

Generates a unique identifier.

Returns:string – UUID.
WebElement.is(other)

Performs an equality check between this web element and <var>other</var>.

Arguments:
  • other (WebElement) – Web element to compare with this.
Returns:

boolean – True if this and <var>other</var> are the same. False otherwise.

WebElement.isReference(obj)

Checks if <var>ref<var> is a {@link WebElement} reference, i.e. if it has {@link ContentWebElement.Identifier}, or {@link ChromeWebElement.Identifier} as properties.

Arguments:
  • string> obj (Object.<string,) – Object that represents a reference to a {@link WebElement}.
Returns:

boolean – True if <var>obj</var> is a {@link WebElement}, false otherwise.