Namespace: element

element

This module provides shared functionality for dealing with DOM- and web elements in Marionette.

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

Each element has an associated web element reference (a UUID) that uniquely identifies the the element across all browsing contexts. The web element reference for every element representing the same element is the same.

The element.Store provides a mapping between web element references and DOM elements for each browsing context. It also provides functionality for looking up and retrieving elements.

Source:

Classes

Store

Methods

(static) coordinates(node, xOffsetopt, yOffsetopt) → {Object.<string, number>}

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.

Parameters:
Name Type Attributes Description
node Node

Target node.
xOffset number <optional>

Horizontal offset relative to target's top-left corner. Defaults to the centre of the target's bounding box.
yOffset number <optional>

Vertical offset relative to target's top-left corner. Defaults to the centre of the target's bounding box.
Source:
Throws:

TypeError If xOffset or yOffset are not numbers.

Returns:

X- and Y coordinates.

Type
Object.<string, number>

(static) find(container, strategy, selector, opts) → {Promise.<(Element|Array.<Element>)>}

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 timeout for the element to appear in the DOM.

See the element.Strategy enum for a full list of supported search strategies that can be passed to strategy.

Available flags for opts:

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

timeout
Duration to wait before timing out the search. If all is false, a NoSuchElementError is thrown if unable to find the element within the timeout duration.

startNode
Element to use as the root of the search.

Parameters:
Name Type Description
container Object.<string, WindowProxy>

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 strategy.
opts Object.<string, ?>

Options.
Source:
Throws:

  • InvalidSelectorError If strategy is unknown.

  • InvalidSelectorError If selector is malformed.

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

Returns:

Single element or a sequence of elements.

Type
Promise.<(Element|Array.<Element>)>

(static) findAnonymousNodes(document, node) → {Iterable.<XULElement>}

Find anonymous nodes of node.

Parameters:
Name Type Description
document XULDocument

Root node of the document.
node XULElement

Where in the DOM hierarchy to begin searching.
Source:
Returns:

Iterator over anonymous elements.

Type
Iterable.<XULElement>

(static) findByLinkText(startNode, linkText) → {Iterable.<HTMLAnchorElement>}

Find all hyperlinks descendant of startNode which link text is linkText.

Parameters:
Name Type Description
startNode Element

Where in the DOM hierarchy to begin searching.
linkText string

Link text to search for.
Source:
Returns:

Sequence of link elements which text is s.

Type
Iterable.<HTMLAnchorElement>

(static) findByPartialLinkText(startNode, linkText) → {Iterable.<HTMLAnchorElement>}

Find all hyperlinks descendant of startNode which link text contains linkText.

Parameters:
Name Type Description
startNode Element

Where in the DOM hierachy to begin searching.
linkText string

Link text to search for.
Source:
Returns:

Iterator of link elements which text containins linkText.

Type
Iterable.<HTMLAnchorElement>

(static) findByXPath(document, startNode, expression) → {Node}

Find a single element by XPath expression.

Parameters:
Name Type Description
document HTMLDocument

Document root.
startNode Element

Where in the DOM hiearchy to begin searching.
expression string

XPath search expression.
Source:
Returns:

First element matching expression.

Type
Node

(static) findByXPathAll(document, startNode, expression) → {Iterable.<Node>}

Find elements by XPath expression.

Parameters:
Name Type Description
document HTMLDocument

Document root.
startNode Element

Where in the DOM hierarchy to begin searching.
expression string

XPath search expression.
Source:
Returns:

Iterator over elements matching expression.

Type
Iterable.<Node>

(static) findClosest(startNode, selector) → {Node}

Finds the closest parent node of startNode by CSS a selector expression.

Parameters:
Name Type Description
startNode Node

Cyce through startNode's parent nodes in tree-order and return the first match to selector.
selector string

CSS selector expression.
Source:
Returns:

First match to selector, or null if no match was found.

Type
Node

(static) getContainer(el) → {Element}

Gets the element's container element.

An element container is defined by the WebDriver specification to be an <option> element in a valid element context, meaning that it has an ancestral element that is either <datalist> or <select>.

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

Parameters:
Name Type Description
el Element

Element to get the container of.
Source:
Returns:

Container element of el.

Type
Element

(static) getInViewCentrePoint(rect, window) → {Map.<string, number>}

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

Parameters:
Name Type Description
rect DOMRect

Element off a DOMRect sequence produced by calling getClientRects on an Element.
window WindowProxy

Current window global.
Source:
Returns:

X and Y coordinates that denotes the in-view centre point of rect.

Type
Map.<string, number>

(static) getPointerInteractablePaintTree(el) → {Array.<DOMElement>}

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.

Parameters:
Name Type Description
el DOMElement

Element to determine if is pointer-interactable.
Source:
Returns:

Sequence of elements in paint order.

Type
Array.<DOMElement>

(static) inViewport(el, xopt, yopt) → {boolean}

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

Parameters:
Name Type Attributes Description
el Element

Target element.
x number <optional>

Horizontal offset relative to target. Defaults to the centre of the target's bounding box.
y number <optional>

Vertical offset relative to target. Defaults to the centre of the target's bounding box.
Source:
Returns:

True if if el is in viewport, false otherwise.

Type
boolean

(static) isBooleanAttribute(el, attr) → {boolean}

Tests if the attribute is a boolean attribute on element.

Parameters:
Name Type Description
el DOMElement

Element to test if attr is a boolean attribute on.
attr string

Attribute to test is a boolean attribute.
Source:
Returns:

True if the attribute is boolean, false otherwise.

Type
boolean

(static) isCollection(seq) → {boolean}

Determines if obj is an HTML or JS collection.

Parameters:
Name Type Description
seq *

Type to determine.
Source:
Returns:

True if seq is collection.

Type
boolean

(static) isDisabled(el) → {boolean}

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

Parameters:
Name Type Description
el Element

Element to test for disabledness.
Source:
Returns:

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

Type
boolean

(static) isDOMElement(node) → {boolean}

Ascertains whether node is a DOM element.

Parameters:
Name Type Description
node *

Element thought to be an Element.
Source:
Returns:

True if node is a DOM element, false otherwise.

Type
boolean

(static) isDOMWindow(node) → {boolean}

Ascertains whether node is a WindowProxy.

Parameters:
Name Type Description
node *

Node thought to be a WindowProxy.
Source:
Returns:

True if node is a DOM window.

Type
boolean

(static) isEditable(Element) → {boolean}

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:

  • It is a <textarea> element.
  • It is an <input> element that is not of the checkbox, radio, hidden, submit, button, or image types.
  • It is content-editable.
  • It belongs to a document in design mode.
Parameters:
Name Type Description
Element Element

to test if editable.
Source:
Returns:

True if editable, false otherwise.

Type
boolean

(static) isEditingHost(el) → {boolean}

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

Parameters:
Name Type Description
el Element

Element to determine if is an editing host.
Source:
Returns:

True if editing host, false otherwise.

Type
boolean

(static) isElement(node) → {boolean}

Ascertains whether node is a DOM-, SVG-, or XUL element.

Parameters:
Name Type Description
node *

Element thought to be an Element or XULElement.
Source:
Returns:

True if node is an element, false otherwise.

Type
boolean

(static) isInView(el) → {boolean}

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 elementsFromPoint list at el's in-view centre coordinates.

Before running the check, we change el'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.

Parameters:
Name Type Description
el Element

Element to check if is in view.
Source:
Returns:

True if el is inside the viewport, or false otherwise.

Type
boolean

(static) isObscured(el) → {boolean}

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.

Parameters:
Name Type Description
el DOMElement

Element determine if is pointer-interactable.
Source:
Returns:

True if element is obscured, false otherwise.

Type
boolean

(static) isReadOnly(el) → {boolean}

An element is considered read only if it is an <input> or <textarea> element whose readOnly content IDL attribute is set.

Parameters:
Name Type Description
el Element

Element to test is read only.
Source:
Returns:

True if element is read only.

Type
boolean

(static) isSelected(el) → {boolean}

Determine if el is selected or not.

This operation only makes sense on

<input type=checkbox>,

<input type=radio>, and >option> elements.

Parameters:
Name Type Description
el DOMElement | XULElement

Element to test if selected.
Source:
Returns:

True if element is selected, false otherwise.

Type
boolean

(static) isStale(elopt, windowopt) → {boolean}

Determines if el 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 window, is a WebDriver concept defining the target against which commands will run. As the current browsing context may differ from el's associated context, an element is considered stale even if it is connected to a living (not discarded) browsing context such as an <iframe>.

Parameters:
Name Type Attributes Description
el Element <optional>

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.
window WindowProxy <optional>

Current browsing context, which may differ from the associate browsing context of el. When retrieving XUL elements, this is optional.
Source:
Returns:

True if el is stale, false otherwise.

Type
boolean

(static) isVisible(el, xopt, yopt) → {boolean}

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

Parameters:
Name Type Attributes Description
el Element

Element to check if visible.
x number <optional>

Horizontal offset relative to target. Defaults to the centre of the target's bounding box.
y number <optional>

Vertical offset relative to target. Defaults to the centre of the target's bounding box.
Source:
Returns:

True if visible, false otherwise.

Type
boolean

(static) isXULElement(node) → {boolean}

Ascertains whether el is a XUL- or XBL element.

Parameters:
Name Type Description
node *

Element thought to be a XUL- or XBL element.
Source:
Returns:

True if node is a XULElement or XBLElement, false otherwise.

Type
boolean

(static) scrollIntoView(el)

Attempts to scroll into view |el|.

Parameters:
Name Type Description
el DOMElement

Element to scroll into view.
Source: