WidgetTester class

A testing harness for TUI widgets that drives events through a real Program instance.

This ensures message coalescing, the update→render cycle, command execution, and all other Program-level behaviour are exercised — matching what happens at runtime.

Mouse/tap interactions use render-tree hit-testing by default.

Constructors

WidgetTester({int screenWidth = 80, int screenHeight = 24, bool enableZones = false})
Creates a new tester.

Properties

app → WidgetApp?
The underlying WidgetApp, or null if pumpWidget hasn't been called.
no setter
elements → List<Element>
Returns all mounted elements in depth-first order.
no setter
find → Finder
A Finder scoped to this tester's latest rendered output.
no setter
gestureZoneIds → List<String>
Returns all gesture zone IDs currently registered.
no setter
hashCode → int
The hash code for this object.
no setterinherited
program → Program<WidgetApp>?
The Program driving this tester, or null before pumpWidget.
no setter
pumpCount → int
Number of times pump has been called (including the implicit pump inside pumpWidget).
no setter
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited
screenHeight ↔ int
Screen height used for WindowSizeMsg and MediaQueryData.
getter/setter pair
screenWidth ↔ int
Screen width used for WindowSizeMsg and MediaQueryData.
getter/setter pair
view → String
The most recently rendered view string.
no setter
viewLines → List<String>
Returns the visible (ANSI-stripped) lines of the last rendered view.
no setter

Methods

dispose() → Future<void>
Tears down the tester, stopping the Program and releasing resources.
elementsWhere(bool predicate(Element element)) → List<Element>
Returns mounted elements that satisfy predicate.
getZone(String zoneId) → ZoneInfo?
Returns the ZoneInfo for zoneId, or null if not registered.
hitTestAt(int x, int y) → List<HitTestElementEntry>
Performs a hit-test at terminal coordinates (x, y) against the render tree and returns the list of hit elements, deepest first.
locateText(String text) → ({int x, int y})?
Finds the terminal coordinates of text in the ANSI-stripped rendered output. Returns null if not found.
mouseDown(int x, int y, {MouseButton button = MouseButton.left}) → void
Sends a mouse press at (x, y) without releasing.
mouseMove(int x, int y) → void
Sends a mouse motion event at (x, y).
mouseUp(int x, int y, {MouseButton button = MouseButton.left}) → void
Sends a mouse release at (x, y).
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
pump() → void
Triggers a render cycle — rebuilds dirty elements and captures the latest rendered output.
pumpWidget(Widget widget, {bool scanZones = false, bool useHitTesting = true, bool debugOverlay = false, DebugOverlayPosition? debugOverlayPosition, int? width, int? height}) → Future<void>
Mounts widget in a WidgetApp wrapped by a Program and performs the initial render.
resize(int width, int height) → void
Rebuilds the widget tree with a new simulated terminal size.
sendKey(String char) → void
Sends a KeyMsg for the given character through the Program pipeline and captures the resulting view.
sendKeyNoPump(String char) → void
Sends a KeyMsg without capturing the view afterwards.
sendMsg(Msg msg) → void
Sends an arbitrary Msg to the Program and captures the view.
sendMsgNoPump(Msg msg) → void
Sends an arbitrary Msg without capturing the view.
sendSpecialKey(KeyType type) → void
Sends a KeyMsg for a special key (e.g. enter, escape, arrow keys).
tap(TapTarget target) → void
Simulates a full tap (press + release) at the location of target.
tapAt(int x, int y) → void
Simulates a full tap (press + release) at raw terminal coordinates.
tapZone(String zoneId) → void
Simulates a full tap on the zone with zoneId.
toString() → String
A string representation of this object.
inherited
viewContains(String text) → bool
Returns true if the latest rendered view contains text.

Operators

operator ==(Object other) → bool
The equality operator.
inherited