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
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.<(nsIDOMElement|Array.<nsIDOMElement>)>}
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, Window> | 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.<(nsIDOMElement|Array.<nsIDOMElement>)>
(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:
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:
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:
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:
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
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, win) → {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 a |DOMElement|. |
win |
nsIDOMWindow | Current browsing context. |
- 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()
Determines if |obj| is an HTML or JS collection.
- Source:
(static) isDisconnected(el, container) → {boolean}
Check if the element is detached from the current frame as well as the optional shadow root (when inside a Shadow DOM context).
Parameters:
| Name | Type | Description |
|---|---|---|
el |
nsIDOMElement | Element to be checked. |
container |
Container | Container with |frame|, which is the window object that contains the element, and an optional |shadowRoot|. |
- Source:
Returns:
Flag indicating that the element is disconnected.
- 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) 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) 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:
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: