Selector.addCustomMethods Method

Adds custom methods executed on the client side to the selector.

Use addCustomMethods to implement selector methods specific to the web app architecture or framework.

Selector().addCustomMethods({
    method1: fn1,
    method2: fn2,
    /* ... */
}, options) → Selector

Parameter	Type	Description
`method1`, `method2`, ...	String	Method names.
`fn1`, `fn2`, ...	Function	Functions that contain method code. Executed on the client side in the browser.
`options`	Object	Custom method options.

Functions that contain method code (fn1, fn2, ...) take the following parameters.

Parameter	Type	Description
`node`	Object \| Array	The DOM node if the returnDOMNodes option is set to `false`; an array of DOM nodes if returnDOMNodes is set to `true`.
`param1`, `param2`, ...	Any	Method parameters.

The addCustomMethods function also adds the specified methods to the element state returned by the selector.

Options #

Option	Type	Description	Default
`returnDOMNodes`	Boolean	`true` if custom methods return DOM nodes; `false` if they return serializable objects.	`false`

Enable returnDOMNodes to use custom method results as selectors to define action targets or assertion's actual values, obtain the element state, etc.

The following example shows how to add both types of methods to a selector. addCustomMethods is called twice: the first call adds a method that returns a DOM node (returnDOMNodes is set to true), the second call defines a method that returns a string.

Example

import { Selector } from 'testcafe';

fixture `My fixture`
    .page `https://js.devexpress.com/`;

test('My test', async t => {
    const myTable = Selector('.dx-datagrid-table')
        .nth(1)
        .addCustomMethods({
            getExpandButtonCell: (elements, rowIndex) => {
                return elements[0].querySelectorAll('.dx-group-row')[rowIndex].cells[0];
            }
            // ...
            // Other methods that return DOM nodes.
        }, {
            returnDOMNodes: true
        })
        .addCustomMethods({
            getCellText: (table, rowIndex, columnIndex) => {
                return table.rows[rowIndex].cells[columnIndex].innerText;
            }
            // ...
            // Other methods that return serializable objects.
        });

    await t
        .expect(myTable.getCellText(3, 1)).contains('Europe')
        .click(myTable.getExpandButtonCell(0))
        .expect(myTable.getCellText(1, 1)).contains('North America');
});

If you use TypeScript, declare a Selector interface extension with your custom methods:

import { Selector } from 'testcafe';

interface CustomSelector extends Selector {
    getCellText(rowIndex: number, columnIndex: number): Promise<any>;
    getExpandButtonCell(rowIndex: number): Promise<any>;
}

fixture `My fixture`
    .page `https://js.devexpress.com/`;

test('My test', async t => {
    const myTable = <CustomSelector>Selector('#customers').addCustomMethods({
        getExpandButtonCell: (elements: HTMLCollection, rowIndex: number) => {
            return elements[0].querySelectorAll('.dx-group-row')[rowIndex].cells[0];
        }
        // ...
        // Other methods that return DOM nodes.
    }, {
        returnDOMNodes: true
    })
    .addCustomMethods({
        getCellText: (table: HTMLTableElement, rowIndex: number, columnIndex: number) => {
            return table.rows[rowIndex].cells[columnIndex].innerText;
        }
        // ...
        // Other methods that return serializable objects.
    });

    await t
        .expect(myTable.getCellText(3, 1)).contains('Europe')
        .click(myTable.getExpandButtonCell(0))
        .expect(myTable.getCellText(1, 1)).contains('North America');
});

Propagation #

Custom methods propagate through the selector chain. You can call them for any subsequent selector:

import { Selector } from 'testcafe';

fixture `My fixture`
    .page `https://devexpress.github.io/testcafe/example/`;

test('Propagate custom properties', async t => {
    const fieldSet = Selector('fieldset').addCustomMethods({
        getInput: (el, idx) => {
            return el[0].querySelectorAll('input')[idx];
        }
    }, {
        returnDOMNodes: true
    });

    await t
        .typeText(fieldSet.getInput(0), 'Peter Parker')
        .click(fieldSet.withText('Operating System').getInput(2))
        .click(fieldSet.withAttribute('id', 'tried-section').getInput(0));
});

Note that TestCafe propagates all custom properties and methods down every selector chain. Ensure that custom code does not fail during propagation:

import { Selector } from 'testcafe';

fixture `My fixture`
    .page `https://devexpress.github.io/testcafe/example/`;

test('Check Label HTML', async t => {
    let fieldSet = Selector('fieldset')
        .addCustomDOMProperties({
            legend: el => el.querySelector('legend').innerText
        })
        .addCustomMethods({
            getLabel: (el, idx) => {
                return el[0].elements[idx].labels[0];
            }
        }, {
            returnDOMNodes: true
        });

    // This assertion passes.
    await t.expect(fieldSet.nth(1).legend).eql('Which features are important to you:');

    // This line throws an error.
    await t.expect(fieldSet.nth(1).getLabel(3).textContent).eql('Easy embedding into a Continuous integration system');

    // When TestCafe evaluates "getLabel(3)", it also tries to propagate
    // the "legend" property to the result. So, it queries for a
    // <legend> inside the <label> element, which returns nothing.
});