UiSelector
UiSelector
ui_selector.UiSelector
Fluent builder for locating UiObject nodes in the accessibility tree: filter with where, tune cardinality / retries / timeout, then first, all, takeAt, etc.
Table of contents
Constructors
Properties
Methods
- all
- atLeast
- atLeastOne
- atMost
- first
- firstOrNull
- findFirst
- findFirstOrNull
- from
- last
- lastOrNull
- findLast
- findLastOrNull
- maxRetries
- takeAt
- takeAtOrNull
- findAt
- findAtOrNull
- timeout
- where
Constructors
constructor
• new UiSelector(): UiSelector
Create an empty selector (call where before executing).
Returns
Properties
defaultUiObjectProvider
static defaultUiObjectProvider: UiObjectProvider
Global root provider used when from is not specified.
Methods
all
▸ all(): Promise<UiObject[]>
Resolve every node matching the current query.
Returns
Promise<UiObject[]>
atLeast
▸ atLeast(min): UiSelector
Require at least min matches before all / multi-result APIs succeed.
Parameters
| Name | Type | Description |
|---|---|---|
min | number | Minimum count. |
Returns
atLeastOne
▸ atLeastOne(): UiSelector
Shorthand for atLeast(1).
Returns
atMost
▸ atMost(max): UiSelector
Cap the number of nodes returned by all (and related collectors).
Parameters
| Name | Type | Description |
|---|---|---|
max | number | Maximum count. |
Returns
first
▸ first(): Promise<UiObject>
First match. Rejects / throws (engine-specific) when none.
Returns
Promise<UiObject>
firstOrNull
▸ firstOrNull(): Promise<UiObject | null>
First match, or null when the tree has no hit.
Returns
Promise<UiObject | null>
findFirst
▸ findFirst(options?): Promise<UiObject>
Like first, but honors FindOptions (polling interval, traversal, …).
Parameters
| Name | Type | Description |
|---|---|---|
options | FindOptions | Optional tuning. |
Returns
Promise<UiObject>
findFirstOrNull
▸ findFirstOrNull(options?): Promise<UiObject | null>
findFirst variant that resolves null instead of failing.
Parameters
| Name | Type | Description |
|---|---|---|
options | FindOptions | Optional tuning. |
Returns
Promise<UiObject | null>
from
▸ from(target): UiSelector
Restrict the search space to descendants of target (selector, single object, array, or custom provider).
Parameters
| Name | Type | Description |
|---|---|---|
target | UiSelector | UiObject | UiObject[] | UiObjectProvider | Root(s) to scan under. |
Returns
last
▸ last(): Promise<UiObject>
Last match in traversal order.
Returns
Promise<UiObject>
lastOrNull
▸ lastOrNull(): Promise<UiObject | null>
Last match, or null.
Returns
Promise<UiObject | null>
findLast
▸ findLast(options?): Promise<UiObject>
last with FindOptions.
Parameters
| Name | Type | Description |
|---|---|---|
options | FindOptions | Optional tuning. |
Returns
Promise<UiObject>
findLastOrNull
▸ findLastOrNull(options?): Promise<UiObject | null>
findLast that returns null when missing.
Parameters
| Name | Type | Description |
|---|---|---|
options | FindOptions | Optional tuning. |
Returns
Promise<UiObject | null>
maxRetries
▸ maxRetries(max): UiSelector
How many times to re-query the tree when matches are temporarily missing (animations, lazy lists).
Parameters
| Name | Type | Description |
|---|---|---|
max | number | Retry attempts. |
Returns
takeAt
▸ takeAt(i): Promise<UiObject>
Zero-based i-th match.
Parameters
| Name | Type | Description |
|---|---|---|
i | number | Match index. |
Returns
Promise<UiObject>
takeAtOrNull
▸ takeAtOrNull(i): Promise<UiObject | null>
takeAt but null when i is out of range.
Parameters
| Name | Type | Description |
|---|---|---|
i | number | Match index. |
Returns
Promise<UiObject | null>
findAt
▸ findAt(i, options?): Promise<UiObject>
takeAt with FindOptions.
Parameters
| Name | Type | Description |
|---|---|---|
i | number | Match index. |
options | FindOptions | Optional tuning. |
Returns
Promise<UiObject>
findAtOrNull
▸ findAtOrNull(i, options?): Promise<UiObject | null>
findAt returning null when absent.
Parameters
| Name | Type | Description |
|---|---|---|
i | number | Match index. |
options | FindOptions | Optional tuning. |
Returns
Promise<UiObject | null>
timeout
▸ timeout(timeout): UiSelector
Maximum time (milliseconds) to keep polling before failing a find* call.
Parameters
| Name | Type | Description |
|---|---|---|
timeout | number | Timeout in ms. |
Returns
where
▸ where(filter): UiSelector
Attach property / hierarchy filters described by a SelectorQuery object or a custom UiObjectFilter predicate.
Parameters
| Name | Type | Description |
|---|---|---|
filter | SelectorQuery | UiObjectFilter | Match rules. |