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.

Available extensions

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
isRecordingFrames → bool
Whether frame recording is currently enabled.
no setter
lastRecordedFrame → WidgetTestFrame?
The most recently recorded frame, or null if no frames were captured.
no setter
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
recordedFrames → List<WidgetTestFrame>
Recorded deterministic frame snapshots captured while recording.
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
terminalOutput → String
Raw terminal output captured by the mock terminal.
no setter
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

advanceAnimation(Object controllerId, ManualClock clock, {Duration delta = Duration.zero}) → void
Advances clock by delta and sends the resulting animation tick.
analyzeFlicker({String runId = 'widget-test', bool requireSynchronizedOutput = false}) → FlickerAnalysis

Available on WidgetTester, provided by the WidgetTesterFlickerAnalysis extension

Runs FlickerAnalyzer over the tester's raw terminal writes.
captureFrame({String trigger = 'captureFrame'}) → void
Records the current frame immediately without requiring a message send.
clearRecordedFrames() → void
Removes all recorded frames and resets the local frame sequence.
dispose() → Future<void>
Tears down the tester, stopping the Program and releasing resources.
drag(int startX, int startY, int endX, int endY, {int steps = 1, MouseButton button = MouseButton.left}) → void
Sends a drag gesture from the start coordinates to the end coordinates.
elementsWhere(bool predicate(Element element)) → List<Element>
Returns mounted elements that satisfy predicate.
fuzz({WidgetFuzzOptions options = const WidgetFuzzOptions()}) → WidgetFuzzResult

Available on WidgetTester, provided by the WidgetTesterFuzzing extension

Runs a deterministic fuzz sequence against this tester.
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
pasteText(String text) → void
Sends text as a single paste payload.
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, ImageAutoMode imageAutoMode = ImageAutoMode.portableFallback, int? width, int? height}) → Future<void>
Mounts widget in a WidgetApp wrapped by a Program and performs the initial render.
recordedFramesSince(int sequence) → List<WidgetTestFrame>
Returns recorded frames whose sequence is greater than sequence.
recordFramesWhile<T>(T action(), {bool clearExisting = true, bool captureCurrentFrame = false}) → T
Runs action while frame recording is enabled and returns the frames.
resize(int width, int height) → void
Rebuilds the widget tree with a new simulated terminal size.
runStorm(WidgetStormProfile profile) → WidgetStormResult

Available on WidgetTester, provided by the WidgetTesterStorming extension

Runs one deterministic storm profile against this tester.
sendAnimationTick(Object controllerId, DateTime time) → void
Sends an AnimationTickMsg with an explicit timestamp.
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).
startFrameRecording({bool clearExisting = true, bool captureCurrentFrame = false}) → void
Starts recording deterministic frame snapshots after each synced render.
stopFrameRecording() → List<WidgetTestFrame>
Stops frame recording and returns the captured frames.
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
typeText(String text) → void
Types text as a sequence of rune key presses.
viewContains(String text) → bool
Returns true if the latest rendered view contains text.

Operators

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