Find element (detailed)
Referenced In
Fields
| Field | Type | Description | Default |
|---|---|---|---|
| surface | one of: - string - object(Browser surface) - object(App surface) | Optional. The browser window/tab or app window this step acts on. Omit to act on the active surface — the most recently opened, focused, or explicitly targeted surface, whatever its kind. Specifying a surface switches the active surface for the steps that follow. App surfaces use the object form ({ “app”: … }). | — |
| elementText | string | Optional. Display text of the element to find. Matched against the element’s full visible text with whitespace normalized (leading/trailing trimmed, internal runs collapsed to single spaces), so text a framework splits across several nodes still matches and a driver’s surrounding whitespace doesn’t cause a miss. Wrap the value in slashes (/pattern/) to match a substring by regular expression instead of the whole normalized text. If combined with other element finding fields, the element must match all specified criteria. | — |
| selector | string | Optional. Selector of the element to find. If combined with other element finding fields, the element must match all specified criteria. | — |
| elementId | string | Optional. ID attribute of the element to find. Supports exact match or regex pattern using /pattern/ syntax. | — |
| elementTestId | string | Optional. data-testid attribute of the element to find. Supports exact match or regex pattern using /pattern/ syntax. | — |
| elementClass | one of: - string - array of string | Optional. Class or array of classes that the element must have. Each class supports exact match or regex pattern using /pattern/ syntax. Element must have all specified classes. | — |
| elementAttribute | object | Optional. Object of attribute key-value pairs that the element must have. Values can be strings (supporting /pattern/ regex), numbers, or booleans. Boolean true matches attribute presence, false matches absence. | — |
| elementAria | string | Optional. Computed accessible name of the element per ARIA specification. Supports exact match or regex pattern using /pattern/ syntax. | — |
| timeout | integer | Optional. Max duration in milliseconds to wait for the element to exist. | 5000 |
| moveTo | boolean | Optional. Move the cursor to the element. If the element isn’t visible, it’s scrolled into view. Off by default — set it explicitly when a step should scroll, or when a recording needs the cursor to travel to the element. | false |
| click | one of: - one of: - string - object(Click element (detailed)) - boolean - object(Find element and click) | Optional. Click the element. | — |
| type | one of: - one of: - string - array of string - object(Type keys (detailed)) | Optional. Type keys after finding the element. Either a string or an object with a keys field as defined in type. To type in the element, make the element active with the click parameter. | — |
Examples
{"surface": "chrome","elementText": "example","selector": "example","elementId": "example","elementTestId": "example","elementClass": "example","elementAttribute": {},"elementAria": "example","timeout": 5000,"moveTo": false,"click": "example"}