Interface: SemanticLocator

@termwright/driver — PTY + VT sessions, locators, actions and waits.

The normative public API lives in api.ts; this module is the only entry point and re-exports the types from there together with their runtime implementations.

Example

import { launchTerminal } from '@termwright/driver';

const terminal = await launchTerminal({ command: ['node', 'app.js'] });
await terminal.waitForText('Ready');
await terminal.getByRole('button', { name: 'Approve' }).activate();
await terminal.close();

Extends

LocatorBase<"semantic">

Properties

description

readonly description: string

Defined in: driver/src/api.ts:583

Human-readable form of the query, as it appears in error messages.

Inherited from

ScreenLocator.description

domain

readonly domain: "semantic"

Defined in: driver/src/api.ts:581

Inherited from

LocatorBase.domain

Methods

actionability()

actionability(action, opts?): Promise<ActionabilityExplanation>

Defined in: driver/src/api.ts:646

Parameters

action

opts?

PointerOptions & object

Returns

Promise<ActionabilityExplanation>

activate()

activate(opts?): Promise<ActionReceipt>

Defined in: driver/src/api.ts:670

Parameters

opts?

WaitOptions

Returns

Promise<ActionReceipt>

and()

and(other): SemanticLocator

Defined in: driver/src/api.ts:587

Parameters

other

SemanticLocator

Returns

SemanticLocator

Inherited from

LocatorBase.and

cellSnapshot()

cellSnapshot(opts?): Promise<LocatorCellSnapshot>

Defined in: driver/src/api.ts:614

Atomic cells inside this locator’s qualified rectangle.

Parameters

opts?

LocatorCellSnapshotOptions

Returns

Promise<LocatorCellSnapshot>

Inherited from

LocatorBase.cellSnapshot

check()

check(opts?): Promise<ActionReceipt>

Defined in: driver/src/api.ts:671

Parameters

opts?

WaitOptions

Returns

Promise<ActionReceipt>

checkpoint()

checkpoint(): ObservationStamp

Defined in: driver/src/api.ts:594

Current committed observation used to arm race-free custom waits.

Returns

ObservationStamp

Inherited from

LocatorBase.checkpoint

click()

click(opts?): Promise<ActionReceipt>

Defined in: driver/src/api.ts:601

Parameters

opts?

PointerOptions

Returns

Promise<ActionReceipt>

Inherited from

LocatorBase.click

count()

count(): Promise<number>

Defined in: driver/src/api.ts:592

Returns

Promise<number>

Inherited from

LocatorBase.count

doubleClick()

doubleClick(opts?): Promise<ActionReceipt>

Defined in: driver/src/api.ts:602

Parameters

opts?

PointerOptions

Returns

Promise<ActionReceipt>

Inherited from

LocatorBase.doubleClick

dragTo()

dragTo(target, opts?): Promise<ActionReceipt>

Defined in: driver/src/api.ts:604

Parameters

target

SemanticLocator

opts?

LocatorDragOptions

Returns

Promise<ActionReceipt>

Inherited from

LocatorBase.dragTo

evaluateCondition()

evaluateCondition(condition, opts?): Promise<ConditionResult>

Defined in: driver/src/api.ts:645

Parameters

extendedState()

extendedState(): Promise<SemanticExtendedObject | null>

Defined in: driver/src/api.ts:683

Returns

Promise<SemanticExtendedObject | null>

fill()

fill(text, opts?): Promise<ActionReceipt>

Defined in: driver/src/api.ts:665

Parameters

text

ExecutableValue

opts?

WaitOptions

Returns

Promise<ActionReceipt>

filter()

filter(options): SemanticLocator

Defined in: driver/src/api.ts:626

Parameters

options

SemanticLocatorFilterOptions

Returns

SemanticLocator

first()

first(): SemanticLocator

Defined in: driver/src/api.ts:584

Returns

SemanticLocator

Inherited from

LocatorBase.first

focus()

focus(opts?): Promise<ActionReceipt>

Defined in: driver/src/api.ts:669

Parameters

opts?

WaitOptions

Returns

Promise<ActionReceipt>

geometry()

geometry(): Promise<LocatorGeometry>

Defined in: driver/src/api.ts:608

Atomic, evidence-qualified geometry. Never invents a rectangle.

Returns

Promise<LocatorGeometry>

Inherited from

LocatorBase.geometry

getByLabel()

getByLabel(text, opts?): SemanticLocator

Defined in: driver/src/api.ts:622

Parameters

text

string | RegExp

opts?

exact?

boolean

Returns

SemanticLocator

getByRole()

getByRole(role, opts?): SemanticLocator

Defined in: driver/src/api.ts:621

Parameters

role

opts?

RoleLocatorOptions

Returns

SemanticLocator

getByTestId()

getByTestId(testId): SemanticLocator

Defined in: driver/src/api.ts:624

Parameters

testId

string

Returns

SemanticLocator

getByText()

getByText(text, opts?): SemanticLocator

Defined in: driver/src/api.ts:623

Parameters

text

string | RegExp

opts?

TextLocatorOptions

Returns

SemanticLocator

hitTest()

hitTest(opts?): Promise<PointerHitTest>

Defined in: driver/src/api.ts:612

Whether pointer input at the chosen cell reaches this exact target.

Parameters

opts?

position?

{ columnOffset: number; rowOffset: number; }

position.columnOffset

number

position.rowOffset

number

Returns

Promise<PointerHitTest>

Inherited from

LocatorBase.hitTest

hover()

hover(opts?): Promise<ActionReceipt>

Defined in: driver/src/api.ts:603

Parameters

opts?

PointerOptions

Returns

Promise<ActionReceipt>

Inherited from

LocatorBase.hover

last()

last(): SemanticLocator

Defined in: driver/src/api.ts:585

Returns

SemanticLocator

Inherited from

LocatorBase.last

locator()

locator(selector): SemanticLocator

Defined in: driver/src/api.ts:625

Parameters

selector

string

Returns

SemanticLocator

nth()

nth(index): SemanticLocator

Defined in: driver/src/api.ts:586

Parameters

index

number

Returns

SemanticLocator

Inherited from

LocatorBase.nth

or()

or(other): SemanticLocator

Defined in: driver/src/api.ts:588

Parameters

other

SemanticLocator

Returns

SemanticLocator

Inherited from

LocatorBase.or

paintedRegion()

paintedRegion(): Promise<Observation<SemanticPaintedRegion>>

Defined in: driver/src/api.ts:679

Exact cells painted by this semantic recipient, never inferred from layout.

Returns

Promise<Observation<SemanticPaintedRegion>>

press()

press(keys, opts?): Promise<ActionReceipt>

Defined in: driver/src/api.ts:660

Parameters

keys

string

opts?

WaitOptions

Returns

Promise<ActionReceipt>

resolve()

resolve(opts?): Promise<ResolvedTarget<"semantic">>

Defined in: driver/src/api.ts:591

Parameters

opts?

WaitOptions

Returns

Promise<ResolvedTarget<"semantic">>

Inherited from

LocatorBase.resolve

semanticScroll()

semanticScroll(): Promise<Observation<SemanticScrollState>>

Defined in: driver/src/api.ts:675

Production application viewport state, never emulator scrollback position.

Returns

Promise<Observation<SemanticScrollState>>

semanticState()

semanticState(): Promise<SemanticState | null>

Defined in: driver/src/api.ts:682

Returns

Promise<SemanticState | null>

semanticValue()

semanticValue(): Promise<SemanticValueObservation>

Defined in: driver/src/api.ts:673

Returns

Promise<SemanticValueObservation>

textContent()

textContent(): Promise<string>

Defined in: driver/src/api.ts:615

Returns

Promise<string>

Inherited from

LocatorBase.textContent

type()

type(text, opts?): Promise<ActionReceipt>

Defined in: driver/src/api.ts:661

Parameters

text

ExecutableValue

opts?

WaitOptions

Returns

Promise<ActionReceipt>

uncheck()

uncheck(opts?): Promise<ActionReceipt>

Defined in: driver/src/api.ts:672

Parameters

opts?

WaitOptions

Returns

Promise<ActionReceipt>

visibility()

visibility(): Promise<LocatorVisibility>

Defined in: driver/src/api.ts:610

Attached/displayed/viewport facts without collapsing unknown to false.

Returns

Promise<LocatorVisibility>

Inherited from

LocatorBase.visibility

waitFor()

waitFor(opts?): Promise<void>

Defined in: driver/src/api.ts:627

Parameters

opts?

object & WaitOptions

Returns

Promise<void>

waitForCheckpointChange()

waitForCheckpointChange(options): Promise<ObservationStamp>

Defined in: driver/src/api.ts:596

Waits for a newer committed observation without a check/subscribe gap.

Parameters

options

object & WaitOptions

Returns

Promise<ObservationStamp>

Inherited from

LocatorBase.waitForCheckpointChange

wheel()

wheel(opts): Promise<ActionReceipt>

Defined in: driver/src/api.ts:605

Parameters

opts

LocatorWheelOptions

Returns

Promise<ActionReceipt>

Inherited from

LocatorBase.wheel

within()

within(parent): SemanticLocator

Defined in: driver/src/api.ts:620

Parameters

parent

SemanticLocator

Returns

SemanticLocator