Hex1bTerminalAutomator

Namespace: Hex1b.Automation

Assembly: Hex1b.dll

Provides an imperative, async API for automating terminal interactions in tests. Each method executes immediately and records its result in a step history, providing rich diagnostic context when failures occur.

public sealed class Hex1bTerminalAutomator

Inheritance

Object → Hex1bTerminalAutomator

Constructors

Hex1bTerminalAutomator(Hex1bTerminal, Hex1bTerminalInputSequenceOptions, TimeSpan)

Creates a new automator for the specified terminal with custom options.

Parameters:

• terminal (Hex1bTerminal): The terminal to automate.
• options (Hex1bTerminalInputSequenceOptions): Options for controlling poll intervals, typing speed, and time provider.
• defaultTimeout (TimeSpan): Default timeout for WaitUntil*Async methods when no explicit timeout is provided.

public Hex1bTerminalAutomator(Hex1bTerminal terminal, Hex1bTerminalInputSequenceOptions options, TimeSpan defaultTimeout)

Hex1bTerminalAutomator(Hex1bTerminal, TimeSpan)

Creates a new automator for the specified terminal.

Parameters:

• terminal (Hex1bTerminal): The terminal to automate.
• defaultTimeout (TimeSpan): Default timeout for WaitUntil*Async methods when no explicit timeout is provided.

public Hex1bTerminalAutomator(Hex1bTerminal terminal, TimeSpan defaultTimeout)

Properties

CompletedSteps

Gets the list of all steps that have completed successfully.

Returns: IReadOnlyList<AutomationStepRecord>

public IReadOnlyList<AutomationStepRecord> CompletedSteps { get; }

Methods

Alt()

Adds Alt modifier to the next key or mouse action.

Returns: Hex1bTerminalAutomator

public Hex1bTerminalAutomator Alt()

BackspaceAsync(CancellationToken, string?, int)

Sends Backspace key.

Parameters:

• ct (CancellationToken):
• callerFilePath (String):
• callerLineNumber (Int32):

Returns: Task

public Task BackspaceAsync(CancellationToken ct = default, string? callerFilePath = null, int callerLineNumber = 0)

ClickAtAsync(int, int, MouseButton, CancellationToken, string?, int)

Performs a click at the specified position.

Parameters:

• x (Int32):
• y (Int32):
• button (MouseButton):
• ct (CancellationToken):
• callerFilePath (String):
• callerLineNumber (Int32):

Returns: Task

public Task ClickAtAsync(int x, int y, MouseButton button = MouseButton.Left, CancellationToken ct = default, string? callerFilePath = null, int callerLineNumber = 0)

CreateSnapshot()

Creates a snapshot of the current terminal state.

Returns: Hex1bTerminalSnapshot

public Hex1bTerminalSnapshot CreateSnapshot()

Ctrl()

Adds Ctrl modifier to the next key or mouse action.

Returns: Hex1bTerminalAutomator

public Hex1bTerminalAutomator Ctrl()

DeleteAsync(CancellationToken, string?, int)

Sends Delete key.

Parameters:

• ct (CancellationToken):
• callerFilePath (String):
• callerLineNumber (Int32):

Returns: Task

public Task DeleteAsync(CancellationToken ct = default, string? callerFilePath = null, int callerLineNumber = 0)

DoubleClickAtAsync(int, int, MouseButton, CancellationToken, string?, int)

Performs a double-click at the specified position.

Parameters:

• x (Int32):
• y (Int32):
• button (MouseButton):
• ct (CancellationToken):
• callerFilePath (String):
• callerLineNumber (Int32):

Returns: Task

public Task DoubleClickAtAsync(int x, int y, MouseButton button = MouseButton.Left, CancellationToken ct = default, string? callerFilePath = null, int callerLineNumber = 0)

DownAsync(CancellationToken, string?, int)

Sends Down arrow key.

Parameters:

• ct (CancellationToken):
• callerFilePath (String):
• callerLineNumber (Int32):

Returns: Task

public Task DownAsync(CancellationToken ct = default, string? callerFilePath = null, int callerLineNumber = 0)

DragAsync(int, int, int, int, MouseButton, CancellationToken, string?, int)

Performs a drag from one position to another.

Parameters:

• fromX (Int32):
• fromY (Int32):
• toX (Int32):
• toY (Int32):
• button (MouseButton):
• ct (CancellationToken):
• callerFilePath (String):
• callerLineNumber (Int32):

Returns: Task

public Task DragAsync(int fromX, int fromY, int toX, int toY, MouseButton button = MouseButton.Left, CancellationToken ct = default, string? callerFilePath = null, int callerLineNumber = 0)

EndAsync(CancellationToken, string?, int)

Sends End key.

Parameters:

• ct (CancellationToken):
• callerFilePath (String):
• callerLineNumber (Int32):

Returns: Task

public Task EndAsync(CancellationToken ct = default, string? callerFilePath = null, int callerLineNumber = 0)

EnterAsync(CancellationToken, string?, int)

Sends Enter key.

Parameters:

• ct (CancellationToken):
• callerFilePath (String):
• callerLineNumber (Int32):

Returns: Task

public Task EnterAsync(CancellationToken ct = default, string? callerFilePath = null, int callerLineNumber = 0)

EscapeAsync(CancellationToken, string?, int)

Sends Escape key.

Parameters:

• ct (CancellationToken):
• callerFilePath (String):
• callerLineNumber (Int32):

Returns: Task

public Task EscapeAsync(CancellationToken ct = default, string? callerFilePath = null, int callerLineNumber = 0)

HomeAsync(CancellationToken, string?, int)

Sends Home key.

Parameters:

• ct (CancellationToken):
• callerFilePath (String):
• callerLineNumber (Int32):

Returns: Task

public Task HomeAsync(CancellationToken ct = default, string? callerFilePath = null, int callerLineNumber = 0)

KeyAsync(Hex1bKey, CancellationToken, string?, int)

Sends a key press event.

Parameters:

• key (Hex1bKey):
• ct (CancellationToken):
• callerFilePath (String):
• callerLineNumber (Int32):

Returns: Task

public Task KeyAsync(Hex1bKey key, CancellationToken ct = default, string? callerFilePath = null, int callerLineNumber = 0)

KeyAsync(Hex1bKey, Hex1bModifiers, CancellationToken, string?, int)

Sends a key press event with explicit modifiers.

Parameters:

• key (Hex1bKey):
• modifiers (Hex1bModifiers):
• ct (CancellationToken):
• callerFilePath (String):
• callerLineNumber (Int32):

Returns: Task

public Task KeyAsync(Hex1bKey key, Hex1bModifiers modifiers, CancellationToken ct = default, string? callerFilePath = null, int callerLineNumber = 0)

LeftAsync(CancellationToken, string?, int)

Sends Left arrow key.

Parameters:

• ct (CancellationToken):
• callerFilePath (String):
• callerLineNumber (Int32):

Returns: Task

public Task LeftAsync(CancellationToken ct = default, string? callerFilePath = null, int callerLineNumber = 0)

MouseMoveToAsync(int, int, CancellationToken, string?, int)

Moves the mouse to an absolute position.

Parameters:

• x (Int32):
• y (Int32):
• ct (CancellationToken):
• callerFilePath (String):
• callerLineNumber (Int32):

Returns: Task

public Task MouseMoveToAsync(int x, int y, CancellationToken ct = default, string? callerFilePath = null, int callerLineNumber = 0)

PageDownAsync(CancellationToken, string?, int)

Sends Page Down key.

Parameters:

• ct (CancellationToken):
• callerFilePath (String):
• callerLineNumber (Int32):

Returns: Task

public Task PageDownAsync(CancellationToken ct = default, string? callerFilePath = null, int callerLineNumber = 0)

PageUpAsync(CancellationToken, string?, int)

Sends Page Up key.

Parameters:

• ct (CancellationToken):
• callerFilePath (String):
• callerLineNumber (Int32):

Returns: Task

public Task PageUpAsync(CancellationToken ct = default, string? callerFilePath = null, int callerLineNumber = 0)

RightAsync(CancellationToken, string?, int)

Sends Right arrow key.

Parameters:

• ct (CancellationToken):
• callerFilePath (String):
• callerLineNumber (Int32):

Returns: Task

public Task RightAsync(CancellationToken ct = default, string? callerFilePath = null, int callerLineNumber = 0)

ScrollDownAsync(int, CancellationToken, string?, int)

Scrolls down at the current mouse position.

Parameters:

• ticks (Int32):
• ct (CancellationToken):
• callerFilePath (String):
• callerLineNumber (Int32):

Returns: Task

public Task ScrollDownAsync(int ticks = 1, CancellationToken ct = default, string? callerFilePath = null, int callerLineNumber = 0)

ScrollUpAsync(int, CancellationToken, string?, int)

Scrolls up at the current mouse position.

Parameters:

• ticks (Int32):
• ct (CancellationToken):
• callerFilePath (String):
• callerLineNumber (Int32):

Returns: Task

public Task ScrollUpAsync(int ticks = 1, CancellationToken ct = default, string? callerFilePath = null, int callerLineNumber = 0)

SequenceAsync(Action<Hex1bTerminalInputSequenceBuilder>, string?, CancellationToken, string?, int)

Builds and runs an input sequence inline. The sequence is tracked as a single step in the automator's history.

Parameters:

• configure (Action<Hex1bTerminalInputSequenceBuilder>): Action to configure the sequence builder.
• description (String): Description for error messages and step history.
• ct (CancellationToken): Cancellation token.
• callerFilePath (String): Auto-captured caller file path. Do not pass explicitly.
• callerLineNumber (Int32): Auto-captured caller line number. Do not pass explicitly.

Returns: Task

public Task SequenceAsync(Action<Hex1bTerminalInputSequenceBuilder> configure, string? description = null, CancellationToken ct = default, string? callerFilePath = null, int callerLineNumber = 0)

SequenceAsync(Hex1bTerminalInputSequence, string?, CancellationToken, string?, int)

Runs a pre-built input sequence. The sequence is tracked as a single step in the automator's history.

Parameters:

• sequence (Hex1bTerminalInputSequence): The pre-built sequence to run.
• description (String): Description for error messages and step history.
• ct (CancellationToken): Cancellation token.
• callerFilePath (String): Auto-captured caller file path. Do not pass explicitly.
• callerLineNumber (Int32): Auto-captured caller line number. Do not pass explicitly.

Returns: Task

public Task SequenceAsync(Hex1bTerminalInputSequence sequence, string? description = null, CancellationToken ct = default, string? callerFilePath = null, int callerLineNumber = 0)

Shift()

Adds Shift modifier to the next key or mouse action.

Returns: Hex1bTerminalAutomator

public Hex1bTerminalAutomator Shift()

SlowTypeAsync(string, TimeSpan?, CancellationToken, string?, int)

Types text slowly with a delay between keystrokes.

Parameters:

• text (String):
• delay (Nullable<TimeSpan>):
• ct (CancellationToken):
• callerFilePath (String):
• callerLineNumber (Int32):

Returns: Task

public Task SlowTypeAsync(string text, TimeSpan? delay = null, CancellationToken ct = default, string? callerFilePath = null, int callerLineNumber = 0)

SpaceAsync(CancellationToken, string?, int)

Sends Space key.

Parameters:

• ct (CancellationToken):
• callerFilePath (String):
• callerLineNumber (Int32):

Returns: Task

public Task SpaceAsync(CancellationToken ct = default, string? callerFilePath = null, int callerLineNumber = 0)

TabAsync(CancellationToken, string?, int)

Sends Tab key.

Parameters:

• ct (CancellationToken):
• callerFilePath (String):
• callerLineNumber (Int32):

Returns: Task

public Task TabAsync(CancellationToken ct = default, string? callerFilePath = null, int callerLineNumber = 0)

TypeAsync(string, CancellationToken, string?, int)

Types text quickly (no delay between keystrokes).

Parameters:

• text (String):
• ct (CancellationToken):
• callerFilePath (String):
• callerLineNumber (Int32):

Returns: Task

public Task TypeAsync(string text, CancellationToken ct = default, string? callerFilePath = null, int callerLineNumber = 0)

UpAsync(CancellationToken, string?, int)

Sends Up arrow key.

Parameters:

• ct (CancellationToken):
• callerFilePath (String):
• callerLineNumber (Int32):

Returns: Task

public Task UpAsync(CancellationToken ct = default, string? callerFilePath = null, int callerLineNumber = 0)

WaitAsync(int, CancellationToken, string?, int)

Pauses for the specified number of milliseconds.

Parameters:

• milliseconds (Int32):
• ct (CancellationToken):
• callerFilePath (String):
• callerLineNumber (Int32):

Returns: Task

public Task WaitAsync(int milliseconds, CancellationToken ct = default, string? callerFilePath = null, int callerLineNumber = 0)

WaitAsync(TimeSpan, CancellationToken, string?, int)

Pauses for the specified duration.

Parameters:

• duration (TimeSpan):
• ct (CancellationToken):
• callerFilePath (String):
• callerLineNumber (Int32):

Returns: Task

public Task WaitAsync(TimeSpan duration, CancellationToken ct = default, string? callerFilePath = null, int callerLineNumber = 0)

WaitUntilAlternateScreenAsync(TimeSpan?, string?, int)

Waits until the terminal enters alternate screen mode.

Parameters:

• timeout (Nullable<TimeSpan>): Maximum time to wait. If null, uses the default timeout.
• callerFilePath (String): Auto-captured caller file path. Do not pass explicitly.
• callerLineNumber (Int32): Auto-captured caller line number. Do not pass explicitly.

Returns: Task

public Task WaitUntilAlternateScreenAsync(TimeSpan? timeout = null, string? callerFilePath = null, int callerLineNumber = 0)

WaitUntilAsync(Func<Hex1bTerminalSnapshot, bool>, TimeSpan?, string?, string?, string?, int)

Waits until a condition is met on the terminal.

Parameters:

• predicate (Func<Hex1bTerminalSnapshot, Boolean>): The condition to wait for. Receives a snapshot of the terminal state.
• timeout (Nullable<TimeSpan>): Maximum time to wait. If null, uses the default timeout.
• description (String): Description for error messages. If not provided, the predicate expression is used.
• predicateExpression (String): Auto-captured predicate source text. Do not pass explicitly.
• callerFilePath (String): Auto-captured caller file path. Do not pass explicitly.
• callerLineNumber (Int32): Auto-captured caller line number. Do not pass explicitly.

Returns: Task

public Task WaitUntilAsync(Func<Hex1bTerminalSnapshot, bool> predicate, TimeSpan? timeout = null, string? description = null, string? predicateExpression = null, string? callerFilePath = null, int callerLineNumber = 0)

WaitUntilNoTextAsync(string, TimeSpan?, string?, int)

Waits until the terminal no longer contains the specified text.

Parameters:

• text (String): The text to wait to disappear.
• timeout (Nullable<TimeSpan>): Maximum time to wait. If null, uses the default timeout.
• callerFilePath (String): Auto-captured caller file path. Do not pass explicitly.
• callerLineNumber (Int32): Auto-captured caller line number. Do not pass explicitly.

Returns: Task

public Task WaitUntilNoTextAsync(string text, TimeSpan? timeout = null, string? callerFilePath = null, int callerLineNumber = 0)

WaitUntilTextAsync(string, TimeSpan?, string?, int)

Waits until the terminal contains the specified text.

Parameters:

• text (String): The text to wait for.
• timeout (Nullable<TimeSpan>): Maximum time to wait. If null, uses the default timeout.
• callerFilePath (String): Auto-captured caller file path. Do not pass explicitly.
• callerLineNumber (Int32): Auto-captured caller line number. Do not pass explicitly.

Returns: Task

public Task WaitUntilTextAsync(string text, TimeSpan? timeout = null, string? callerFilePath = null, int callerLineNumber = 0)

Remarks

The automator layers on top of — each method builds its own input sequence under the covers and runs it via . The flow is always: automator method → sequencer → steps.

When a step fails (e.g., a times out), the automator wraps the exception in which includes the full step history, terminal snapshot, and source location for debugging.

Examples

var auto = new Hex1bTerminalAutomator(terminal, defaultTimeout: TimeSpan.FromSeconds(5));
await auto.WaitUntilTextAsync("File");
await auto.EnterAsync();
await auto.WaitUntilTextAsync("New");
await auto.DownAsync();
await auto.WaitUntilAsync(s => IsSelected(s, "Open"), description: "Open to be selected");
await auto.EnterAsync();