TwkTester class final

Runs an app under test: the real binding on a terminal in memory (terminal), the real parser decoding the bytes of the input, the emulator reconstructing the screen from the bytes of the frames.

Time is a FakeClock's: the app's timers, the frames and the pause after a lone ESC wait until pump moves the clock on. Each call of the tester runs the app's microtasks before it returns; an error the app ends with is thrown by the call during which it ended, or by the next one.

A frame waits for the clock: what a key changes shows once pump has moved it on by a frame's gap.

testTwk('the screen shows a frame once the clock moves on', (t) async {
  await t.pumpWidget(const Text('Ready'), size: (20, 2));
  expect(t.lines.first, 'Ready');
  expect(t, matchesScreen('Ready'));
  await t.pump(const Duration(seconds: 1));
  expect(t.clock.elapsed, greaterThan(const Duration(seconds: 1)));
});

See also:

Available extensions

Properties

binding → AppBinding
The binding running the app.
no setter
clock ↔ FakeClock
The time of the app.
latefinal
cursor → (int, int)
Where the cursor is: column and row of the screen.
no setter
cursorVisible → bool
Whether the terminal shows the cursor.
no setter
frames → List<RecordedFrame>
The frames the app wrote so far, in order: each write to the terminal (HeadlessTerminal.frames) with its time on the clock and the screen it left, replayed on an emulator of its own that resizes where the terminal did.
no setter
hashCode → int
The hash code for this object.
no setterinherited
isRunning → bool
Whether the app started and has not ended.
no setter
lines → List<String>
The rows of the screen as text, without the blanks that end them, a wide glyph once.
no setter
logs → LogSink
The app's log: print, log() and the errors it reports.
final
mode → ScreenMode
The screen mode the app runs in.
no setter
pointerShape → PointerShape?
The shape the app gave the mouse pointer last (PointerShape, OSC 22): PointerShape.arrow where it shows the terminal's default, null before it gave any. A StateError without pumpWidget(pointerShapes: true), where the terminal shows none: a null read there would be no finding.
no setter
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited
scrollback → List<String>
Inline mode: the lines scrolled off the top of the screen, oldest first, as lines gives rows.
no setter
stderrLines → List<String>
What the app wrote to stderr, line by line: the warnings and errors of its log, once it ended.
no setter
terminal → HeadlessTerminal
The terminal the app runs on: HeadlessTerminal.frames holds every frame it wrote.
no setter
viewportLines → List<String>
The rows of the app's viewport (see pumpWidget) as lines gives the screen's, from its first column: as many of its rows and columns as the screen has. A StateError for an app in none.
no setter
vt → Vt
The emulator, fed every frame written so far.
no setter

Methods

act(FutureOr<void> fn()) → Future<void>
Runs fn in the app's zone, as the app's own code runs, then pumps a frame (pump): how a test changes what the app listens to (a controller, a notifier, a cubit) and sees the frame that follows.
cell(int x, int y) → VtCell
The cell of the screen at column x and row y: its text, colors and attributes, which are numbers as Color and Attr are (0 for the terminal's default color).
click(int x, int y, {int button = 0}) → Future<void>
Presses button at the cell (x, y) and releases it there.
clickOn(Finder finder, {int button = 0}) → Future<void>

Available on TwkTester, provided by the FinderTester extension

Clicks button on the widget finder finds (TwkTester.click): on the cell in the middle of those it shows, its own cut off where they are outside one of the render objects above it, as a hit test cuts them. A StateError when it shows none.
element(Finder finder) → Element

Available on TwkTester, provided by the FinderTester extension

The element of the widget finder finds.
input(List<int> bytes) → Future<void>
Delivers bytes as one read of the terminal's input. As a terminal does, what the parser holds after them — a lone ESC, an open paste — is resolved once the clock has moved on by HeadlessTerminal.inputTimeout without more input.
linesIn(CellRect region) → List<String>
Reads the rows of region, a rectangle of the screen as FinderTester.rect gives one, as lines gives the screen's: the text of its cells, a wide glyph once, from the region's first column and without the blanks that end a row; as many of its rows and columns as the screen has. A wide glyph cut by the region's left or right edge is left out, so that the rows are exactly the region's cells.
linesOf(Finder finder) → List<String>

Available on TwkTester, provided by the FinderTester extension

The rows of the cells of the widget finder finds (rect), as TwkTester.linesIn gives them.
mouse(MouseKind kind, int x, int y, {int button = 0, int modifiers = 0}) → Future<void>
Delivers the mouse report (SGR, mode 1006) of kind at the cell (x, y), 0-based, with button (0 left, 1 middle, 2 right, 8 to 11 the side buttons) for a press, release or drag, and modifiers (Mod's Shift, Alt and Ctrl). A StateError in the inline mode, where the terminal keeps the mouse for itself, but in a viewport (see pumpWidget), whose app gets the events in its own cells.
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
paste(String text) → Future<void>
Pastes text as a terminal with bracketed paste does: between its start and end markers, in one read.
press(String keys) → Future<void>
Presses each key of keys in turn, as the bytes the terminal sends for it, a read each: keys named as key bindings name them, apart by spaces (KeyCombo.parseSequence): ctrl+s, shift+tab, A, g g, ctrl+x ctrl+s. A FormatException names a typo.
pump([Duration? duration]) → Future<void>
Moves the clock on by duration, by default the gap between two frames (a second over the binding's maxFps): what is due by then runs — timers, frames, a lone ESC resolved — in order, so a frame asked for before the call has run when it returns.
pumpUntilIdle({Duration timeout = const Duration(seconds: 10)}) → Future<void>
Pumps frame gap after frame gap, as pump does, until the app is idle: a gap passed without a frame written and none of the app's timers waits (a frame asked for is one, the next tick of an animation another). A TestFailure once the clock has moved on by timeout and the app is still busy: it says how many frames the app wrote and when the next of its timers is due, and shows the screen and the render tree, as a failing matcher does.
pumpWidget(Widget widget, {(int, int)? size, ScreenMode? mode, Duration? duration, List<String> history = const [], Viewport? viewport, bool kittyKeyboard = false, int? backgroundRgb, Multiplexer multiplexer = Multiplexer.none, NotificationProtocol notifications = NotificationProtocol.none, GraphicsProtocol graphics = GraphicsProtocol.none, (int, int)? cellPixels, int maxFps = 60, int? maxInlineRows, bool clearInlineOnExit = false, bool exitOnCtrlC = true, Map<String, String> environment = const {}, DateTime? startTime, bool pointerShapes = false, bool remote = false}) → Future<void>
The first call starts the app showing widget, on a terminal of size (columns, rows; 80 × 24 by default) in mode (fullscreen by default); a later one shows widget in place of the one shown before (state is kept where widgets match, as in any rebuild) and, given another size, resizes the terminal first (resize). Then pumps as pump does for duration.
quit() → Future<void>
Quits the app, unless it has ended, and runs it until it has: the terminal is restored, the tree unmounted. Throws the error it ended with, unless a call threw it already.
rect(Finder finder) → CellRect

Available on TwkTester, provided by the FinderTester extension

The cells of the widget finder finds, as its render object was laid out last: full screen, those of the screen; in the inline mode, those of the region, row 0 its first. Partly or wholly off the screen when the widget is. A StateError before it was laid out.
renderObject<T extends RenderObject>(Finder finder) → T

Available on TwkTester, provided by the FinderTester extension

The render object of the widget finder finds, or of the nearest widget below it that has one; a StateError if there is none, or one that is not a T.
resize(int width, int height) → Future<void>
The terminal becomes width × height cells, and the app gets a ResizeEvent. On the alternate screen the emulator fills the cells with junk, which the app has to paint over; the normal screen of the inline mode keeps what it shows (see Vt.resizeKeeping).
state<T extends State<StatefulWidget>>(Finder finder) → T

Available on TwkTester, provided by the FinderTester extension

The state of the stateful widget finder finds; a StateError if it has none, or one that is not a T.
takeErrors() → List<LogRecord>
The errors the app logged since the last call, oldest first, taken from the test: each one the test does not take fails it when it ends, as testTwk says. An error at LogLevel.error counts: a build, a layout or a paint that threw, an async provider's with no catchError, the app's own. Those of the error the app ended with, the same object, are not among them: a call of the tester throws that. logs still has what is taken; reading logs takes nothing.
toString() → String
The app's screen mode and the terminal's size, fullscreen, 80×24, and whether it has ended; no app before pumpWidget.
override
type(String text) → Future<void>
Delivers text as typed: its UTF-8 bytes as one read (input), which the parser makes a key of each character.
widget<T extends Widget>(Finder finder) → T

Available on TwkTester, provided by the FinderTester extension

The widget finder finds; a StateError if it is not a T.
writeTrace(String path) → void
Writes the frames so far to the file at path as an output trace (Trace in twk_core), each at its time on the clock, which dart run tool/replay.dart --trace plays. Its size is the terminal's when the app started; it has no resizes, nor the inline mode's history. addTearDown(() => t.writeTrace(path)) keeps the frames of a test that fails.
written({int since = 0}) → String
What the app wrote to the terminal, as text: the bytes of the frames (HeadlessTerminal.frames) from frame since on, by default all of them, decoded as UTF-8, a byte that is not as U+FFFD. What a test looks for in it is a sequence the screen does not show: a mode set, the clipboard written (OSC 52), a notification, a scroll.

Operators

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

Static Properties

defaultStartTime → DateTime
The app's wall time (AppBinding.now) when clock reads zero, unless pumpWidget is given another: midnight at the start of 2026, fixed, so a screen that shows a date is the same on every run.
final