@thesoulfresh/interactors

Interactors and matchers for use with @interactors (a.k.a. bigtest).

All interactors provided by this package work against ARIA semantics so if your tests are passing, your accessibility is also decent (though that's no replacement for actual accessibility testing).

API

• src
  • interactors
    • Button
    • printElements
    • GlobalActions
    • GlobalFilters
    • HTML
    • Table
    • TextField
  • matchers
    • matchingArray
    • containingArray
    • matchingObject
    • containingObject
    • any
    • anything
    • is
    • greaterThan
    • greaterThanOrEqualTo
    • greaterThanOrEqual
    • lessThan
    • lessThanOrEqualTo
    • lessThanOrEqual
  • util
    • elementText
    • elementContent
    • getLabel

src

interactors

Button

Extends the @interactors/html:Button with the standard interactors and actions from the HTML interactor from this package.

Additional Filters:

• testId
• testID
• label
• text
• role

Additional Actions:

• debugDOM Pretty print the current DOM.

InteractorConstructor

Defined in

• src/interactors/button.js:21

printElements

▸ printElements(el) => void

Print an element DOM to the console.

Parameters

Name	Type	Default Value	Description
el		-	-

Returns

void

Defined in

• src/interactors/html.js:16

GlobalActions

Provides actions you can merge into any interactor. Gives you the following actions:

• debugDOM

Defined in

• src/interactors/html.js:32

GlobalFilters

Filters you can merge into any interactor. Gives you the following filters:

• testId
• testID
• label
• text
• role

Defined in

• src/interactors/html.js:47

HTML

An element interactor that extends the HTML interactor from @interactors/html but also adds:

Filters

• testId : '[data-testid]' Get an element by its test id.
• label : '[aria-label]' Get an element by its accessibility label.
• text : Get by trimmed text content.
• role : '[role]' Get by accessibility role.

Actions

• debugDOM : Print the DOM of the interactor

Function

Defined in

• src/interactors/html.js:70

Table

Interact with <table> elements.

Selector: table

Locator: The aria-label or the text from the aria-labelled by of the table.

Extends: {@link HTML}

Filters:

• columnCount {number} The number of columns in the table.
• rowCount {number} The number of rows including header rows.
• dataCount {number} The number of rows excluding header rows.
• headers {string[]} The text from each of the header columns.
• cellValues {string[]} The text or input value of each table cell. This will be a multidimensional array of row and cells (ex. [['cell value', 'cell value', 'cell value'], ['cell value', ...]...])
• dataValues {string[]} The same as cellValues but excluding the header cells.

Actions:

• debugDOM Print the interactor DOM

Example Usage:

// Given the HTML
<table aria-label="Monthly Views">
  <thead>
    <tr>
      <th>Month</th>
      <th>Views</th>
    </tr>
    <tbody>
      <tr>
        <td>January</td>
        <td>10</td>
      </tr>
      <tr>
        <td>February</td>
        <td>8</td>
      </tr>
    </tbody>
  </thead>
</table>


it('should have the correct cell data.', await () => {
  const table = Table('Monthly Views');
  await table.has({columnCount: 2});
  await table.has({rowCount: 3});
  await table.has({dataCount: 2});
  await table.has({cellValues: [
    ['Month'   , 'Views'],
    ['January' ,    '10'],
    ['February',     '8']
  ]);
});

any

Defined in

• src/interactors/table.js:80

TextField

Extends the @interactors/html:TextField with the standard interactors and actions from the HTML interactor from this package.

Additional Filters:

• testId
• testID
• label
• text
• role

Additional Actions:

• debugDOM Pretty print the current DOM.

InteractorConstructor

Defined in

• src/interactors/textfield.js:21

matchers

matchingArray

▸ matchingArray(expected) => void

Check that the contents of a list match the given list (including order). Order is important and all values must match. Nested matchers are taken into account. Similar to Jest expect(actual).toEqual(['Foo', bar, 0]).

Example:

// The `value` filter of Foo must be an array with two
// elements 'Foo' and anything else, in that order.
Foo().has({value: matchingArray(['Foo', any(Number)])});

Parameters

Name	Type	Default Value	Description
expected	any	-	The list to match against which may include sub-matchers.

Returns

void

Defined in

• src/matchers/matchers.js:162

containingArray

▸ containingArray(expected) => void

Check that an array includes the given items in any order. Nested matchers are taken into account. Similar to Jest expect.arrayContaining.

Example:

// The `value` filter of Foo must be an array that includes
// the strings 'Foo' and 'Bar' in any order.
Foo().has({value: containingArray(['Foo', 'Bar']);

Parameters

Name	Type	Default Value	Description
expected	any	-	-

Returns

void

Defined in

• src/matchers/matchers.js:192

matchingObject

▸ matchingObject(expected) => void

Check that the expect object has all of the same properties of the actual object. This is most useful as a sub-matcher inside of containingArray or matchingArray. Nested matchers are taken into account. Similar to Jest expect(thing).toEqual({name: 'foo'})

// The `value` filter of Foo must be an object with
// only one property. The property must be 'name'
// and its value must be the string 'foo'.
Foo().has({value: matchingObject({name: 'foo'})});

Parameters

Name	Type	Default Value	Description
expected	any	-	-

Returns

void

Defined in

• src/matchers/matchers.js:225

containingObject

▸ containingObject(expected) => void

Check that the expect object is a subset of the properties of the actual object. Nested matchers are taken into account. Similar to Jest expect.objectContaining

// The `value` filter of Foo must be an object with
// only one property. The property must be 'name'
// and its value must be the string 'foo'.
Foo().has({value: {name: 'foo'}});

Parameters

Name	Type	Default Value	Description
expected	any	-	-

Returns

void

Defined in

• src/matchers/matchers.js:252

any

▸ any(expected) => void

Match any type constructor in the same manner as Jest expect.any.

For example:

TextField().has({placeholder: any(String)});
Foo().has({thing: any(Number)});

Parameters

Name	Type	Default Value	Description
expected	Function	-	A type constructor that you expect the actual value to be.

Returns

void

Defined in

• src/matchers/matchers.js:277

anything

▸ anything() => void

Match any value in the same manner as Jest expect.anything()

Returns

void

Defined in

• src/matchers/matchers.js:294

is

▸ is(expected) => void

Strict equality check (ie ===).

Parameters

Name	Type	Default Value	Description
expected	any	-	-

Returns

void

Defined in

• src/matchers/matchers.js:306

greaterThan

▸ greaterThan(expected) => void

Match any number greater than the given value.

Parameters

Name	Type	Default Value	Description
expected	number	-	-

Returns

void

Defined in

• src/matchers/matchers.js:353

greaterThanOrEqualTo

▸ greaterThanOrEqualTo(expected) => void

Match any number greater than or equal to the given value.

Parameters

Name	Type	Default Value	Description
expected	number	-	-

Returns

void

Defined in

• src/matchers/matchers.js:370

greaterThanOrEqual

▸ greaterThanOrEqual(expected) => void

alias for greaterThanOrEqualTo

Parameters

Name	Type	Default Value	Description
expected	number	-	-

Returns

void

Defined in

• src/matchers/matchers.js:384

lessThan

▸ lessThan(expected) => void

Match any number less than the given value.

Parameters

Name	Type	Default Value	Description
expected	number	-	-

Returns

void

Defined in

• src/matchers/matchers.js:390

lessThanOrEqualTo

▸ lessThanOrEqualTo(expected) => void

Match any number less than or equal to the given value.

Parameters

Name	Type	Default Value	Description
expected	number	-	-

Returns

void

Defined in

• src/matchers/matchers.js:407

lessThanOrEqual

▸ lessThanOrEqual(expected) => void

Alias for lessThanOrEqualTo

Parameters

Name	Type	Default Value	Description
expected	number	-	-

Returns

void

Defined in

• src/matchers/matchers.js:421

util

elementText

▸ elementText(element) => string

Get the text inside of an element. This is similar to the innerText function from @interactors/core but will also trim the text.

Parameters

Name	Type	Default Value	Description
element	HTMLElement	-	-

Returns

string

Defined in

• src/util/text-matching.js:41

elementContent

▸ elementContent(el, checks, collect) => string

Get the "user readable" value from an element. This can include its text, aria-label, input values, etc.

This function is most useful if don't know the type of element you are reading and it could be one of multiple different types (ex. input or div). For example, given an array of table cells containing plain text and inputs, you could get the readable text for all of them using elements.map(el => elementContent(el, ['text', 'value']).

You can customize the order that values are retrieved and which types of content are searched for using the checks parameter. If the element includes multiple children with the same type of content, you can either recieve just the first value or collect them into a comma separated string using the collect parameter.

// Given the following HTML
<div>
  <span>Hello World</span>
  <input value="foo" />
  <input value="bar" />
</div>

// Get the text content only...
const text = elementContent(el);
// -> 'Hello World'

// Get the input values...
const values = elementContent(el, ['value']);
// -> 'foo, bar'

// Get the input values and then the text...
const combined = elementContent(el, ['value', 'text'], true);
// -> 'foo, bar, Hello World'

Parameters

Name	Type	Default Value	Description
el	HTMLElement	-	-
checks		...	The list of content types to retrieve. Your options are 'text', 'value' for inputs, 'label' for aria-label.
collect	boolean	false	false = return the value of the first matching content type. true = use all matching values.

Returns

string

Defined in

• src/util/text-matching.js:133

getLabel

▸ getLabel(el) => string

Get the label text associated with an element. If the element has multiple object that define it's label, they will be combined with a space.

Parameters

Name	Type	Default Value	Description
el	any	-	-

Returns

string

Defined in

• src/util/text-matching.js:174