JSDoc: Namespace: element

# 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:
  - element.js, line 46

### 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:
  - element.js, line 667

##### 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:
  - element.js, line 240

##### 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) findByLinkText(node, s) → {Array.<DOMAnchorElement>}

Find all hyperlinks dscendant of |node| which link text is |s|.

##### Parameters:

Name | Type | Description
--- | --- | ---
`node` | DOMElement | Where in the DOM hierarchy to being searching.
`s` | string | Link text to search for.

Source:
  - element.js, line 381

##### Returns:

Sequence of link elements which text is |s|.

Type
  Array.<DOMAnchorElement>

#### (static) findByPartialLinkText(node, s) → {Array.<DOMAnchorElement>}

Find all hyperlinks descendant of |node| which link text contains |s|.

##### Parameters:

Name | Type | Description
--- | --- | ---
`node` | DOMElement | Where in the DOM hierachy to begin searching.
`s` | string | Link text to search for.

Source:
  - element.js, line 396

##### Returns:

Sequence of link elements which text containins |s|.

Type
  Array.<DOMAnchorElement>

#### (static) findByXPath(root, startNode, expr) → {DOMElement}

Find a single element by XPath expression.

##### Parameters:

Name | Type | Description
--- | --- | ---
`root` | DOMElement | Document root
`startNode` | DOMElement | Where in the DOM hiearchy to begin searching.
`expr` | string | XPath search expression.

Source:
  - element.js, line 339

##### Returns:

First element matching expression.

Type
  DOMElement

#### (static) findByXPathAll(root, startNode, expr) → {Array.<DOMElement>}

Find elements by XPath expression.

##### Parameters:

Name | Type | Description
--- | --- | ---
`root` | DOMElement | Document root.
`startNode` | DOMElement | Where in the DOM hierarchy to begin searching.
`expr` | string | XPath search expression.

Source:
  - element.js, line 358

##### Returns:

Sequence of found elements matching expression.

Type
  Array.<DOMElement>

#### (static) getContainer(el) → {Element}

Gets the element's container element.

An element container is defined by the WebDriver specification to be an element in a valid element context (https://html.spec.whatwg.org/#concept-element-contexts), meaning that it has an ancestral element that is either or

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:
  - element.js, line 737

##### 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:
  - element.js, line 864

##### 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:
  - element.js, line 895

##### 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:
  - element.js, line 704

##### 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:
  - element.js, line 989

##### Returns:

True if the attribute is boolean, false otherwise.

Type
  boolean

#### (static) isCollection()

Determines if |obj| is an HTML or JS collection.

Source:
  - element.js, line 577

#### (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:
  - element.js, line 779

##### 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:
  - element.js, line 843

##### Returns:

True if element is obscured, false otherwise.

Type
  boolean

#### (static) isStale(el) → {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.

##### Parameters:

Name | Type | Description
--- | --- | ---
`el` | Element | DOM element to check for staleness.

Source:
  - element.js, line 633

##### 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:
  - element.js, line 806

##### Returns:

True if visible, false otherwise.

Type
  boolean

#### (static) isWebElementReference(ref) → {boolean}

Checks if |ref| has either |element.Key| or |element.LegacyKey| as properties.

##### Parameters:

Name | Type | Description
--- | --- | ---
`ref` | Object.<string, string> | Object that represents a web element reference.

Source:
  - element.js, line 610

##### Returns:

True if |ref| has either expected property.

Type
  boolean

#### (static) scrollIntoView(el)

Attempts to scroll into view |el|.

##### Parameters:

Name | Type | Description
--- | --- | ---
`el` | DOMElement | Element to scroll into view.

Source:
  - element.js, line 937