Grok JS Marker (Puppeteer) API v1.0

Class: ElementGroup

ElementGroup

An Element Group is an unordered collection of elements that groups together logically with a particular selector. ElementGroup objects cannot be instantiated directly -- use api.getElementGroup instead.

new ElementGroup()

Example
// Grab a handle to a group of elements:
const allInner = api.getElementGroup('.inner', 'div', 'an', 'inner {div} element');

// Perform an action on each element in the group, in turn:
allInner.click();

// Test something that every element should have in common:
allInner.expectComputedStyles({'border-radius': '20px', 'padding': '5px', 'font-size': '20px'});

Members

aOrAn

One of ['a', 'an'] as appropriate for the (singular) 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'.

descriptionPlural

Pluralised description of the element, with the first occurrence of 'element' changed to 'elements'.

selector

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

Methods

click( [options])

Click on all the elements. 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.

evaluate(fn, args)

Execute a function in the browser context, with all group DOM elements available as the first parameter.

Parameters:
Name Type Argument Description
fn PageElementGroupFunction

Function to execute inside the user's page. The first argument will be a list of DOM Element objects
args * <repeatable>

Additional arguments to pass to the function.
Returns:

The result of the PageElementGroupFunction.

Type
*

expectAttr(attr, expectedValue [, options])

Expect a particular value for an attribute for every element in the group. Shorthand for using expectAttrs() with a single key-value pair.

Parameters:
Name Type Argument Description
attr string

name of the attribute, e.g. 'src'
expectedValue string
options Object <optional>

expectAttrs(attrObject [, options])

Expect a set of attributes on every 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 certain style values associated with all our matching elements. Note that if you expect the style attribute not to be set, use an expected value of 'none' as appropriate to the style.

Parameters:
Name Type Argument Description
style string

name of the style attribute to check e.g. 'background-color'
expected string
options Object <optional>
Properties
Name Type Description
afterTransition string

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

expectComputedStyles(styleObject [, options])

Expect certain style values associated with all our matching elements. 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 transition to occur before checking.

expectCount(nExpected [, options])

Checks that the number of elements in our group matches what we expect.

Parameters:
Name Type Argument Description
nExpected number

The number of elements we expect to be present
options Object <optional>
Properties
Name Type Argument Description
numActual Number <optional>

The number of elements we have recently observed. If blank, we look up the current number of elements in the DOM.
atLeast Boolean <optional>

[false] Set to true to change the validation to require 'at least' as many elements as expected, rather than the exact number. TODO
hint string <optional>

An optional string to show if there is a test failure.

expectOrderedTextContent(expectedStrings [, options])

Compare each element's text content against the list of strings given. The failure text here will use ordinality to describe specific elements that fail the test.

Parameters:
Name Type Argument Description
expectedStrings Array.<string>
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.

getComputedStyle(styleAttr)

Get the unformatted value of the requested style attribute for all our elements.

Parameters:
Name Type Description
styleAttr string

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

Each entry is an unformatted value. Use formatStyleValue for pretty printing.

Type
Array.<BaseString>

getComputedStyles(styleAttrs)

Returns a sub-set of the style map, fetching specific style attributes for all our elements.

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

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

Returns a list for all elements of the style object, filtered for the styleAttrs requested.

Type
Array.<StyleAttributeMap>

getElementAtIndex(index)

Grabs the n-th element handle for our selector and return it as an Element. The description for the element is changed to reflect its current ordinal position in the ElementGroup.

Parameters:
Name Type Description
index string

Integer index for the element we want to retrieve a handle for.
Returns:
Type
Element

getTextContent( [options])

Get the text content for all elements in the group, returned as an Array. 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:

An array of strings. The whitespace inside the string will be collapsed by default unless overriden by the options.

Type
Array.<string>