Interface: TerminalHarness

@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();

Properties

artifactSecurity

readonly artifactSecurity: ResolvedArtifactSecurityPolicy

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

Resolved policy inherited by traces, reports and other artifact sinks.

events

readonly events: SessionEvents

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

exit

readonly exit: Promise<ExitStatus>

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

keyboard

readonly keyboard: Keyboard

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

One physical keyboard implementation. Convenience methods delegate here.

mouse

readonly mouse: Mouse

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

One physical mouse implementation. Locator actions delegate here after planning.

scrollback

readonly scrollback: ScrollbackApi

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

selection

readonly selection: SelectionApi

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

sessionId

readonly sessionId: string

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

shell

readonly shell: ShellApi

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

Shell command boundaries and prompt state when the child emits OSC 133.

terminalProfile

readonly terminalProfile: TerminalProfileId

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

Immutable terminal profile used to decode the very first PTY byte.

terminalState

readonly terminalState: TerminalState

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

Emulator facts captured together at the current screen revision.

window

readonly window: TerminalWindow

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

Terminal-window focus reports, distinct from semantic element focus.

Methods

appLogs()

appLogs(): readonly AppLogEvent[]

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

Bounded, oldest-first application-log history, including entries emitted while launchTerminal() was still starting. Consumers should subscribe to app-log first and then seed from this snapshot to avoid a startup gap.

Returns

readonly AppLogEvent[]

bindOperationBudget()?

optional bindOperationBudget(budget): void

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

Binds one attempt-wide budget before any user operation starts.

Parameters

budget

OperationBudget

Returns

void

cell()

cell(pos): CellSnapshot

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

Parameters

pos

column

number

row

number

Returns

CellSnapshot

checkpoint()

checkpoint(): ObservationStamp

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

Atomic identity of the currently committed terminal/semantic observation.

Returns

ObservationStamp

close()

close(): Promise<void>

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

Idempotent; bounded physical cleanup. Never sends signals implicitly.

Returns

Promise<void>

contract()

contract(): EffectiveSessionContract | null

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

Frozen negotiated contract, or null until negotiation has completed.

Returns

EffectiveSessionContract | null

crashReport()

crashReport(): CrashReport | null

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

What the session knew when the program died unexpectedly, or null — for a live session, a clean exit, or one the harness asked for via close() or signal(). Available as soon as the exit event fires.

Returns

CrashReport | null

diagnostics()

diagnostics(): readonly SessionDiagnostic[]

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

Bounded, oldest-first log of what the session decided behind the scenes: dropped or superseded revisions, unverified markers, adapter negotiation, protocol violations. The same entries are emitted as diagnostic events.

Returns

readonly SessionDiagnostic[]

getByLabel()

getByLabel(text, opts?): SemanticLocator

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

Parameters

text

string | RegExp

opts?

exact?

boolean

Returns

SemanticLocator

getByRole()

getByRole(role, opts?): SemanticLocator

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

Parameters

role

opts?

RoleLocatorOptions

Returns

SemanticLocator

getByScreenText()

getByScreenText(text, opts?): ScreenLocator

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

Physical terminal-grid text, optionally narrowed by occurrence or style.

Parameters

text

string | RegExp

opts?

ScreenTextLocatorOptions

Returns

ScreenLocator

getByTestId()

getByTestId(testId): SemanticLocator

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

Parameters

testId

string

Returns

SemanticLocator

getByText()

getByText(text, opts?): SemanticLocator

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

Semantic text only. Never falls back to the terminal grid.

Parameters

text

string | RegExp

opts?

TextLocatorOptions

Returns

SemanticLocator

locator()

locator(selector): SemanticLocator

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

Advanced Termwright semantic selector: ‘dialog button.primary:focused’, ‘#id’.

Parameters

selector

string

Returns

SemanticLocator

locatorForRef()

Call Signature

locatorForRef(ref): SemanticLocator

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

Rebuilds a locator from a ref returned by a resolved target. ('semantic:n8@42' for a semantic node, 'screen:r,c,w,h@7' for a grid match). The ref stays bound to its revision: resolving it after that revision was superseded raises stale-snapshot.

Parameters

ref

`semantic:${string}@${number}`

Returns

SemanticLocator

Call Signature

locatorForRef(ref): ScreenLocator

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

Parameters

ref

`screen:${number},${number},${number},${number}@${number}`

Returns

ScreenLocator

Call Signature

locatorForRef(ref): SemanticLocator | ScreenLocator

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

Parameters

ref

LocatorRef

Returns

SemanticLocator | ScreenLocator

ownedProcessResources()

ownedProcessResources(): OwnedProcessResourceUsage | null

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

Native whole-tree accounting captured immediately before PTY disposal. Returns null when the backend cannot make an authoritative claim.

Returns

OwnedProcessResourceUsage | null

paste()

paste(text): Promise<void>

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

Parameters

text

ExecutableValue

Returns

Promise<void>

press()

press(keys): Promise<void>

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

Parameters

keys

string

Returns

Promise<void>

resize()

resize(size): Promise<ResizeReceipt>

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

Parameters

size

columns

number

rows

number

Returns

Promise<ResizeReceipt>

screen()

screen(): ScreenSnapshot

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

Returns

ScreenSnapshot

semanticTree()

semanticTree(): SemanticSnapshot | null

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

Returns

SemanticSnapshot | null

settled()

settled(opts?): Promise<EffectiveSessionContract>

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

Waits for the one frozen Effective Session Contract and, for a semantic session, for the first paired tree. There is no provisional capability API.

Parameters

opts?

WaitOptions

Returns

Promise<EffectiveSessionContract>

signal()

signal(sig): Promise<void>

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

Parameters

sig

"INT" | "TERM" | "KILL" | "HUP"

Returns

Promise<void>

title()

title(): string

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

Returns

string

type()

type(text): Promise<void>

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

Parameters

text

ExecutableValue

Returns

Promise<void>

waitForCheckpointChange()

waitForCheckpointChange(options): Promise<ObservationStamp>

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

Wait until a committed observation newer than after is available.

Parameters

options

object & WaitOptions

Returns

Promise<ObservationStamp>

waitForCommittedObservation()

waitForCommittedObservation(opts?): Promise<ObservationStamp>

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

Waits until currently observable parser work, semantic frame pairing and provider-evidence invalidation have committed. This cannot predict a future semantic frame before either of its causal signals reaches the driver, and it is not a quiet/global-idle heuristic.