Selector.with Method

Overwrites Selector options.

Use the with method to create Selector queries with options that differ from the base Selector class.

selector.with( options ) → Selector

The with method returns a modified copy of the Selector object. The method keeps base Selector options unless you explicitly overwrite them. To overwrite a Selector option, pass it to the with method as an argument.

The example below includes a with method that overwrites the visibilityCheck option:

import { Selector } from 'testcafe';

const elementWithId = Selector(id => document.getElementById(id));

fixture`Selector.with`
    .page`http://devexpress.github.io/testcafe/example/`;

test('Visible button exists', async t => {
    const visibleElementWithId = elementWithId.with({
        visibilityCheck: true,
    });
    const visibleButton        = await visibleElementWithId('submit-button');

    await t.expect(visibleButton).ok();
});

Options

options.boundTestRun

Type: Object

The boundTestRun option binds the TestController object to a Node.js callback. This is necessary to execute Selectors inside the callback function.

For more information, see the Advanced Selector Techniques guide.

options.dependencies

Type: Object

Selector functions can access the properties of the dependencies object as variables.

Use the dependencies option if you want to share data with a Selector function, but do not want to pass it as an argument.

The following code example includes a Selector function that receives a server-side object (customId) as a dependency:

import { Selector } from 'testcafe';

const persistentId = { key: 'id' };

const element = Selector(() => {
    return document.querySelector(`[${persistentId.key}="submit-button"]`);
}, {
    dependencies: { persistentId },
});

fixture`Initialize selector with function on client side with dependencies`
    .page`https://devexpress.github.io/testcafe/example/`;

test('Click on submit', async t => {
    await t.click(element);
});

TypeScript cannot find client function dependencies during compilation because TestCafe adds dependencies to the function’s scope at runtime. This can cause an error:

Error: TypeScript compilation failed.
Cannot find name 'dependencyFoo'.

To suppress the error, add the // @ts-ignore comment to the test file.

options.timeout

Type: Number

Time in milliseconds. If TestCafe fails to resolve the Selector query within this time limit, the test fails.

Default value: 3000. You can change the default value with the runner.run method or the --selector-timeout command line option.

options.visibilityCheck

Type: Boolean

If the visibilityCheck option is true, TestCafe imposes a visibility requirement on Selector targets.

TestCafe does not interact with invisible elements.

If the element or one of its parents meets the following criteria, TestCafe considers the element to be invisible.

  • The value of the element’s display property is none
  • The value of the element’s visibility property is hidden or collapse
  • The element has a width or height of 0.

Elements that do not meet these criteria may still be invisible to the user. The following factors do not influence the element’s visibility status:

  • The element’s z-index
  • The element’s opacity
  • The element’s position on the page

If the Selector query target does not become visible within the Selector timeout, the query fails.

The visibilityCheck option is not a filter function, and does not change the results of the query. TestCafe still counts invisible elements when you examine the count property:

<html>
  <body>
    <div>This div is visible</div>
    <div style="display:none">This div not is visible</div>
    <div style="visibility:hidden">This div not is visible either</div>
  </body>
</html>

const count = await Selector('div', { visibilityCheck: true }).count;

// returns 3 since the visibilityCheck option
// does not affect the selector's matched set

To filter elements by visibility, use the following Selector methods: filterVisible, filterHidden.

Default value: false