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:
- FinderTester, what it reads of the widgets a Finder finds.
- containsLine, matchesScreen and the other matchers of its screen.
- 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.arrowwhere it shows the terminal's default, null before it gave any. A StateError withoutpumpWidget(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.framesholds 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
fnin 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
xand rowy: its text, colors and attributes, which are numbers asColorandAttrare (0for the terminal's default color). -
click(
int x, int y, {int button = 0}) → Future< void> -
Presses
buttonat the cell (x,y) and releases it there. -
clickOn(
Finder finder, {int button = 0}) → Future< void> -
Available on TwkTester, provided by the FinderTester extension
Clicksbuttonon the widgetfinderfinds (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 widgetfinderfinds. -
input(
List< int> bytes) → Future<void> -
Delivers
bytesas 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 byHeadlessTerminal.inputTimeoutwithout 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 widgetfinderfinds (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
kindat the cell (x,y), 0-based, withbutton(0 left, 1 middle, 2 right, 8 to 11 the side buttons) for a press, release or drag, andmodifiers(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
textas a terminal with bracketed paste does: between its start and end markers, in one read. -
press(
String keys) → Future< void> -
Presses each key of
keysin 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'smaxFps): 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
TestFailureonce the clock has moved on bytimeoutand 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 ofsize(columns, rows; 80 × 24 by default) inmode(fullscreen by default); a later one showswidgetin place of the one shown before (state is kept where widgets match, as in any rebuild) and, given anothersize, resizes the terminal first (resize). Then pumps as pump does forduration. -
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 widgetfinderfinds, 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 widgetfinderfinds, or of the nearest widget below it that has one; a StateError if there is none, or one that is not aT. -
resize(
int width, int height) → Future< void> -
The terminal becomes
width×heightcells, and the app gets aResizeEvent. 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 widgetfinderfinds; a StateError if it has none, or one that is not aT. -
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
testTwksays. An error atLogLevel.errorcounts: a build, a layout or a paint that threw, an async provider's with nocatchError, 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 appbefore pumpWidget.override -
type(
String text) → Future< void> -
Delivers
textas 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 widgetfinderfinds; a StateError if it is not aT. -
writeTrace(
String path) → void -
Writes the frames so far to the file at
pathas an output trace (Tracein twk_core), each at its time on the clock, whichdart run tool/replay.dart --traceplays. 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 framesinceon, 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