Skip to main content
BuyLog In
TestCafe Studio
Search in…
Docs > Test Actions > Element Selectors
A newer version of this page is available. .
All docs
V1.2
TestCafe Studio
Getting Started
Video Tutorials
Guides
Test Directory Structure
Test Actions
Element Selectors
Assertions
On-Page Actions
Debug Actions
Browser Actions
Switch Frames
Statements
Custom Scripts
User Interface
References
Migration Guides
FAQ
Version History

Element Selectors

  • 12 minutes to read

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 two ways to create element selectors:

Auto-Generated Element Selectors

TestCafe Studio can generate element selectors while recording in the following cases:

  • When you interact with a webpage.

    TestCafe Studio records on-page actions, automatically generates element selectors for target elements, and adds them to the Element Selector parameter.

    Element selector

  • When you pick a webpage element with the element picker.

    To pick a target element on the page, 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 Types

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

Element selectors list

The following selector types are available:

Type Matching Element Examples
id An element with the specified id. 1. matches an element with id="populate" : '#populate'
2. matches an element with an auto-generated id:
'div' > withAttribute('id', /test1_ctl\d+_test2/)
attr An element with the specified attribute.
The following attributes can be used: alt, name, class, title, and data.		 1. one attribute: '[name="name"]'
2. multiple attributes: '.some-class[alt="someAlt"]' > withAttribute('data-attr', /foo\s+bar/)
dom An element in the DOM hierarchy. 'body' > find('form') > find('div') > find('header') > find('h1')
html The <html> element. 'html'
body The <body> element. 'body'
text An element with the specified innerText property.
For <option> elements, a textContent property is used to generate element selectors.		 'p' > withText('This webpage')
form-input Finds a form with the specified id or attribute, then finds an input element with the specified name attribute. '#main-form' > find('[name="name"]')
id-dom Finds an element with the specified id, then finds its descendants in the DOM hierarchy. '#main-form' > find('div') > find('header') > find('h1')
id-attr Finds an element with the specified id, then finds its descendants with the specified attribute. '#main-form' > find('[name="preferred-interface"]')
id-text Finds an element with the specified id, then finds its descendants with the specified text. '#main-form' > find('label') > withText('testing on remote devices')
attr-attr Finds an element with the specified attribute, then finds its descendants with the specified attribute. '.column.col-1' > find('[name="name"]')
attr-dom Finds an element with the specified attribute, then finds its descendants in the DOM hierarchy. '.column.col-1' > find('fieldset') > find('input')
attr-text Finds an element with the specified attribute, then finds its descendants with the specified text. '.column.col-1' > find('label') > withText('testing on remote devices')
text-dom Finds an element with the specified text, then finds its descendants in the DOM hierarchy. 'fieldset' > withText('Example') > find('header') > find('p')
text-attr Finds an element with the specified text, then finds its descendants with the specified attribute. 'fieldset' > withText('Your name') > find('[name="name"]')

Elements Highlighting

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

Element Selector Constructor

Use the element selector constructor to create an element selector. The constructor allows you to specify a base selector and add methods to extend this selector.

The constructor is available:

Example

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

NOTE

  • 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

    NOTE

    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

NOTE

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

Add 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.

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 drag the added methods to reorder them.

Reuse Element Selectors

The Define Element Selector action allows you to create an element selector and use it later in the test.

To create an element selector:

  1. Add the Define Element Selector action from the Actions panel.

  2. Specify the element selector's name in the Name field.

    NOTE

    Selector names must be unique in a test. You also cannot use the following reserved words: t, fixture, test, Selector, ClientFunction, RequestLogger, RequestMock, RequestHook.

  3. Use the element selector constructor to define the element selector.

Action icon

You can use the created element selectors in on-page actions and assertions. The main benefits are:

  • The element selector's short name makes tests easier to read.

  • You can define an element selector once and use it in several test actions. If the tested webpage changes, you need to edit the element selector in the Define Element Selector action, but do not need to edit other actions. This makes your tests easier to maintain.

    Benefits

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.

Element Selector Methods

The element selector constructor provides two groups of selector methods:

Filter Elements

The Filter Elements group contains methods that filter a matching set returned by a base selector.

nth(index)

Finds an element by its index in a matching set. The index parameter is zero-based. If index is negative, the index is counted from the end of a matching set.

For example:

  • nth(2) - Selects the third element.
  • nth(-1) - Selects the last element.

withText(text)

Filters a matching set by the specified text. Selects elements that contain this text. The text parameter is case-sensitive.

To filter elements by strict match, use the withExactText method.

withText(re)

Filters a matching set using the specified regular expression, for example, withText(/a[b-e]/).

withExactText(text)

Filters a matching set by the specified text. Selects elements whose text content strictly matches this text. The text parameter is case-sensitive.

To search for elements that contain a specific text, use the withText method.

withAttribute(attrName)

Finds elements that contain the specified attribute.

The Attribute Name parameter is a string or a regular expression.

For example, withAttribute('myAttr') selects elements that have the myAttr attribute. This attribute can have any value.

withAttribute(attrName, attrValue)

Finds elements that contain the specified attribute with the specified value.

The Attribute Name and Attribute Value parameters are strings or regular expressions.

For example:

  • withAttribute('attrName', 'foo') - Selects elements whose attrName attribute is set to foo. Does not match the otherAttr attribute, or the attrName attribute with the foobar value.

  • withAttribute(/[123]z/, /a[0-9]/) - Selects elements that have an attribute whose name matches the /[123]z/ regular expression. This attribute must have a value that matches the /a[0-9]/ regular expression. Matches the '1z' and '3z' attributes with the 'a0' and 'a7' values. Does not match the '4z' or '1b' attribute, as well as any attribute with the 'b0' or 'ab' value.

filterVisible()

Filters a matching set leaving only visible elements. These are elements that do not have the display: none or visibility: hidden CSS properties and have a non-zero width and height.

filterHidden()

Filters a matching set leaving only hidden elements. These are elements that have the display: none or visibility: hidden CSS property or a zero width or height.

filter(cssSelector)

Finds elements that match the specified CSS selector.

For example, filter('.someClass') selects elements that have the someClass class.

filter(filterFunction)

Filters elements using filterFunction. This function takes each element in a matching set and check if the element satisfies the specified conditions.

The function takes the following parameters:

Parameter Description
node The current DOM node.
idx The current node's index among other nodes in a matching set.
NOTE

You cannot use the following within the filter function:

The Search for Related Elements group contains methods that find related elements for elements returned by a base selector.

find

  • find(cssSelector) - Finds all descendants of all elements in a matching set and filters them by the specified CSS selector.

  • find(filterFunction) - Finds all descendants of all elements in a matching set and filters them using the filter function.

parent

  • parent() - Finds all parents of all elements in a matching set (the first element in the set will be the closest parent).

  • parent(index) - Finds all parents of all elements in a matching set and filters them by index (0 is the closest). If index is negative, the index is counted from the end of a matching set.

  • parent(cssSelector) - Finds all parents of all elements in a matching set and filters them by the specified CSS selector.

  • parent(filterFunction) - Finds all parents of all elements in a matching set and filters them using the filter function.

child

  • child() - Finds all child elements of all elements in a matching set.

  • child(index) - Finds all child elements of all elements in a matching set and filters them by index. The index parameter is zero-based. If index is negative, the index is counted from the end of a matching set.

  • child(cssSelector) - Finds all child elements of all elements in a matching set and filters them by the specified CSS selector.

  • child(filterFunction) - Finds all child elements of all elements in a matching set and filters them using the filter function.

sibling

  • sibling() - Finds all sibling elements of all elements in a matching set.

  • sibling(index) - Finds all sibling elements of all elements in a matching set and filters them by index. The index parameter is zero-based. If index is negative, the index is counted from the end of a matching set.

  • sibling(cssSelector) - Finds all sibling elements of all elements in a matching set and filters them by the specified CSS selector.

  • sibling(filterFunction) - Finds all sibling elements of all elements in a matching set and filters them using the filter function.

nextSibling

  • nextSibling() - Finds all succeeding sibling elements of all elements in a matching set.

  • nextSibling(index) - Finds all succeeding sibling elements of all elements in a matching set and filters them by index. The index parameter is zero-based. If index is negative, the index is counted from the end of a matching set.

  • nextSibling(cssSelector) - Finds all succeeding sibling elements of all elements in a matching set and filters them by cssSelector.

  • nextSibling(filterFunction) - Finds all succeeding sibling elements of all elements in a matching set and filters them using the filter function.

prevSibling

  • prevSibling() - Finds all preceding sibling elements of all elements in a matching set.

  • prevSibling(index) - Finds all preceding sibling elements of all elements in a matching set and filters them by index. The index parameter is zero-based. If index is negative, the index is counted from the end of a matching set.

  • prevSibling(cssSelector) - Finds all preceding sibling elements of all elements in a matching set and filters them by the specified CSS selector.

  • prevSibling(filterFunction) - Finds all preceding sibling elements of all elements in a matching set and filters them using the filter function.

Filter Elements with a Function

The Search for Related Elements methods allow you to filter a matching set with a filter function. The function takes each element in the matching set and checks if the element satisfies some conditions.

The function takes the following parameters.

Parameter Description
node The current matching node.
idx The current node's index among other matching nodes.
originNode The node whose parents/siblings/children is currently being iterated.

The following example demonstrates how to use a filter function in the find method.

Filter function

NOTE

You cannot use the following within the filter function: