Element Selectors

Element selectors identify webpage elements in tests. You can use element selectors to define target elements for on-page actions and assertions.

Create Element Selectors

There are three ways to create element selectors:

Auto-Generated Element Selectors

When you interact with a webpage during recording, TestCafe Studio records on-page actions, automatically generates element selectors for target elements and adds them to the Element Selector parameter.

Element selector

TestCafe Studio produces a set of element selectors for each target element. To see all available element selectors, click the button next to the CSS Selector input.

Element selectors list

When you focus or modify the CSS selector in the action parameters, you can see all the matching elements highlighted on the webpage. The feature is available only during recording.

Highlighted element

Use the Element Picker to Generate Element Selectors

Use an element picker to select a target element on the tested webpage during recording. To do this, click the Element Picker button next to the Element Selector field in the test action parameters area and select the element on the webpage. TestCafe Studio generates element selectors for this element and adds one to the Element Selector parameter.

Picking an element

Element Selector Constructor

Create an element selector using the element selector constructor. It allows you to specify a base selector and add methods to extend this selector.

The constructor is available:


The animation below demonstrates how to create an element selector that:

  1. finds all ul elements on a page;
  2. finds label elements in each ul element;
  3. finds a parent that matches the div.container selector for each label element.

Then you can use the created element selector in on-page actions, for example, in the Click action.

Element selector constructor

  • An element selector can return multiple elements. If you use this selector in an on-page action, the action is performed on the first matching element. If you use it in an assertion, the assertion checks properties for the first element.

  • If added methods filter out all elements, an element selector returns null. If a test action or an assertion uses this selector, the test fails.

Base Selector

In the element selector constructor, you first specify a base selector that returns a matching set of elements.

The base selector can be one of the following types:

  • CSS Selector - A CSS selector string that matches one or more elements. For example, you can specify #submit-button for a webpage element with id="submit-button".

    Selector type

  • Function - A regular function that returns an element or array of elements. Use functions when you need to implement custom logic to get a target element.

    Selector type


    You cannot use the following within this function:

  • Element Selector - A stored element selector that you define in the Define Element Selector action. Note that you can use this selector or extend it by adding selector methods.

    Selector type


If you specify a selector in the constructor during recording, all matching elements are highlighted on the webpage.

Selector Methods

In the element selector constructor, you can add one or more element selector methods to filter the matching set or search for related elements. The methods are called one by one.

Add Methods

To add a method, click the Add Method button and select a method in the list.

Add method

Specify the method's parameters (if needed) and click Done.

Method parameters

Remove Methods

To remove a method, select it in the constructor and click the Remove button.

Remove method

Reorder Methods

You can also drag the added methods to reorder them.

Element Selector Timeout

When an on-page action or an assertion uses an element selector, TestCafe Studio waits for the target element to appear in the DOM hierarchy and become visible within the element selector timeout. You can set the timeout in the run configuration's Advanced options.

If TestCafe Studio cannot find the target element in the DOM, the test fails.

See Wait for an Action's Target Element for more information.