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));


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

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



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.


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`

test('Click on submit', async t => {

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.


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 method or the --selector-timeout command line option.


Type: Boolean

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

The element is visible if:

  • The value of the element’s display property is not none
  • The value of the element’s visibility property is not hidden
  • The element has a non-zero width and height

Elements that meet the visibility criteria above 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:

    <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>
const count = await Selector('div', { visibilityCheck: true }).count; // should return 3

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

Default value: false