Grok JS Marker (Puppeteer) API v1.0

Class: Element

Element

Allows the test case to track and interact with a specific DOM element. Tracking an Element will prevent it from being garbage collected in the user page, allowing you to detect whether or not the element is still in the DOM (or not). You can continue to test features of the element even when the element is no longer in the DOM, except where DOM information is necessary (examining computed styles, for example). Element objects cannot be instantiated directly -- use api.getElement instead.

new Element()

Example
// Grab a handle to a page element:
const button = api.getElement('input[type="submit"]', 'input', 'a', 'submit button element');

// Perform an action on the element:
button.click();

// Test something about the element:
button.expectAttr('type', 'submit');

// Test that the element is no longer in the DOM:
button.expectDeleted();

Members

aOrAn

One of ['a', 'an'] as appropriate for the description, e.g. 'an input element' or 'a paragraph tag'

description

Description of the element, in singular form e.g. 'input element' or 'paragraph tag'

selector

This is the selector used with querySelector() to retrieve the element from the DOM.

Methods

action(actionDescription, actionFn [, options])

Perform an action on the element that the student should know about (e.g. interacting with our DOM element to trigger an event). The action is a function that is executed in the browser context, using our element handle as the first parameter. The action description will be listed in the failure report if a subsequent test check fails.

Parameters:
Name Type Argument Description
actionDescription string

Describes the action performed (past tense). E.g. `Cleared the text in the ${element.description} and unfocused it.`
actionFn PageElementFunction

Executed in the browser context.
options Object <optional>

[{}]

Properties
Name Type Argument Description
nTimes Number <optional>

[1] Number of times to perform the action.
Example
// Perform a generic action on the element -- Mark the string as a SafeString to avoid formatting disappointment.
element.action(api.S(`Focused the ${element.description} and unfocused it`), (element) => {
  element.focus();
  element.blur();
});

click( [options])

Click the middle of the element. The options can be passed through to puppeteer to choose which button and the number of clicks and so on.

Parameters:
Name Type Argument Description
options Object <optional>

Puppeteer mouse click options, plus the following:

Properties
Name Type Argument Description
nTimes Number <optional>

[1] number of times to perform the action.

dispose()

Explicitly dispose of the element handle to allow garbage collection in the user page.

evaluate(fn, args)

Execute a function in the browser context, using our element handle as the first parameter. If you expect your function to make changes in the page that the student should know about (e.g. triggering an event handler), use action instead. FIXME: Test what happens if we do an evaluate() that causes a page navigation.

Parameters:
Name Type Argument Description
fn PageElementFunction

Function to execute inside the user's page. The first argument should be the element (DOM node).
args * <repeatable>

Additional arguments to pass to the function.
Returns:

The result from the PageElementFunction.

Type
*

expectAttr(attr, expectedValue)

Expect a particular value for an attribute for a specific selector. Shorthand for using expectAttrs() with a single key-value pair. See also expectNotAttr.

Parameters:
Name Type Description
attr string

name of the attribute, e.g. 'src'
expectedValue string

expectAttrs(attrObject [, options])

Expect a set of attributes on the element to have the desired values.

Parameters:
Name Type Argument Description
attrObject AttributeMap

key/value pairs, with each key an attribute that you wish to check.
options Object <optional>

expectComputedStyle(style, expected [, options])

Expect a certain style value associated with our element.

Parameters:
Name Type Argument Description
style string

name of the style attribute to check e.g. 'background-color'
expected string

Use 'none' (or as appropriate for the style) if you expect the attribute not to be set.
options Object <optional>
Properties
Name Type Description
afterTransition string

number of milliseconds to allow for a CSS transition to occur before checking.

expectComputedStyles(styleObject [, options])

Expect certain style values associated with our element. Note that if you expect the style attribute not to be set, use an expected value of 'none' as appropriate for the style.

Parameters:
Name Type Argument Description
styleObject StyleAttributeMap

key/value pairs, with keys for each style attribute you wish to check
options Object <optional>
Properties
Name Type Description
afterTransition string

number of milliseconds to allow for a CSS transition to occur before checking.

expectDeleted( [options])

Expect that our element is no longer present in the DOM.

Parameters:
Name Type Argument Description
options Object <optional>

expectExists( [options])

Expect that our element still exists in the DOM.

Parameters:
Name Type Argument Description
options Object <optional>

expectNotAttr(attr, undesirableValue)

Expect that the attribute is not set to the given undesirable value.

Parameters:
Name Type Description
attr string

name of the attribute, e.g. 'src'
undesirableValue string

expectTextContent(expected [, options])

Check for matching textContent. By default, we collapse whitespace inside the textContent and expected.text in order to do exact string comparison. Turn this off with the noCollapse option.

Parameters:
Name Type Argument Description
expected string

This is matched exactly against the textContent of the element, after collapsing whitespace.
options Object <optional>
Properties
Name Type Argument Description
noCollapse boolean <optional>

[false] Override default behaviour, which is to strip and collapse the whitespace in the textContent before checking.
hint string <optional>

If present, this is shown after the failure message details, to give extra feedback to the user.

expectValue(expectedValue)

Validate the value of our element.

Parameters:
Name Type Description
expectedValue string

getAttr(attr [, options])

Get the value of an attribute for the element, or an empty string if the attribute is not set.

Parameters:
Name Type Argument Description
attr string
options Object <optional>
Properties
Name Type Argument Description
failIfMissing boolean <optional>

[false] Set to true to fail the test if the attribute is not set.
Returns:

The escaped value of the attribute.

Type
BaseString

getComputedStyle(styleAttr)

Get the unformatted value of the requested style attribute.

Parameters:
Name Type Description
styleAttr string

style attribute requested, e.g. 'top' or 'background-color' etc.
Returns:

An unformatted value. Use formatStyleValue for pretty printing.

Type
BaseString

getComputedStyles(styleAttrs)

Returns a sub-set of the style map, fetching specific style attributes from the specific element. Returns a mapping of style to value for a specific element (a sub-set of the full style on the element).

Parameters:
Name Type Argument Description
styleAttrs Array.<string> <repeatable>

style attributes requested, e.g. 'top' or 'background-color' etc.
Returns:

Returns an object with only the style attributes requested. Values are unformatted, see formatStyleValue for pretty printing.

Type
StyleAttributeMap

getElement(selector, tag, aOrAn, description)

Fetches an element handle for the given selector, searching the DOM using the current element sub-tree. We fail the test case if the selector is not found in the Element sub-tree.

Parameters:
Name Type Description
selector string
tag string
aOrAn string

precedes the description wherever we would refer to 'an element'.
description string

describes the element in the singular, e.g. 'cookie element' or '"Add" button'. Occurrences of '<tag>' are reformatted. For example, with a tag set to 'li', a description of <li> element will become <code data-lang="tag">li</code> element.
Returns:
Type
Element

getTextContent( [options])

Get the element textContent. By default, we collapse whitespace inside the textContent. Turn this off with the noCollapse option.

Parameters:
Name Type Argument Description
options Object <optional>
Properties
Name Type Argument Description
noCollapse boolean <optional>

[false] Override default behaviour, which is to strip and collapse the whitespace in the textContent before checking.
Returns:

The textContent with whitespace collapsed, as required.

Type
BaseString

getValue()

Get the value of our element.

Returns:

A string-like object which contains the escaped value from the element.

Type
BaseString

isInDOM()

Returns true if the element is still connected to the DOM.

Returns:

True, if the element is still connected to the DOM.

Type
boolean

isSameElement(otherElement)

Returns true if the otherElement object passed is referring to the same DOM element as ours inside the user's page.

Parameters:
Name Type Description
otherElement Element

mouseDown( [options])

Perform a mouse down action, onto the centre of the element.

Parameters:
Name Type Argument Description
options Object <optional>

Puppeteer mouse down options.

mouseUp( [options])

Perform a mouse up action, after moving to the centre of the element.

Parameters:
Name Type Argument Description
options Object <optional>

Puppeteer mouse up options.

setValueByTyping(toValue [, options])

Set the value for a particular DOM element by typing into the element. This will clear the existing value in the element.

Parameters:
Name Type Argument Description
toValue string

string to enter into the input.
options Object <optional>