twk_test
Tests for apps built with twk. A test runs the real app on a terminal in memory, presses keys, clicks, and checks the screen the user would see.
Features
- The real app:
testTwkruns your widget underrunApp's binding, not a stand-in, so a test sees what the user sees. - A fake clock: timers, animations and frames wait for the test, which
moves time with
pump. No test waits on the wall clock. - Input as a terminal sends it:
press('ctrl+s'),type('text'),paste,clickandresize, decoded by the same parser the app uses. - The screen as text:
lines,cell(x, y)for colors and attributes, the cursor and the scrollback, read from a strict terminal emulator that fails on a sequence a real terminal would not take. - Matchers:
containsLine,hasTextAt,styleAt,cursorAt, andmatchesScreenfor a snapshot of the screen, with its styles or from a golden file. - Finders:
find.byType,find.byKey,find.text, to click a widget or read its state and the cells it covers. - Failures that explain themselves: a failing matcher shows the screen, the widget tree and the render tree, and a failing test shows its last frames and the app's log.
- More: the emulator and a terminal for programs on twk's console, a
Shotof a widget without an app, and helpers for tests that run a process.
Getting started
dart pub add dev:twk_test
A counter and a test of it. Save it as test/counter_test.dart and run
dart test:
import 'package:test/test.dart';
import 'package:twk/twk.dart';
import 'package:twk_test/twk_test.dart';
final class Counter extends StatefulWidget {
const Counter({super.key});
@override
State<Counter> createState() => _CounterState();
}
final class _CounterState extends State<Counter> {
var _n = 0;
@override
Widget build(BuildContext context) => KeyBindings({
'up': () => setState(() => _n++),
}, child: Text('Count: $_n'));
}
void main() {
testTwk('Up counts', (t) async {
await t.pumpWidget(const Counter(), size: (20, 3));
expect(t, containsLine('Count: 0'));
await t.press('up up up');
await t.pump();
expect(t, containsLine('Count: 3'));
});
}
Learn more
- Example: a counter with a snapshot of the screen, a style check and a quit.
- Guide: writing a test, time, input, errors.
- The screen: reading it, matchers, golden files, finders and frames.
- Other libraries:
the emulator,
Shot,FakeClockon its own, and tests that run processes. - How it is tested: for those who work on the package.
License
MIT, copyright 2026 Andrii Ivanov: LICENSE.
Libraries
- cli
- Test support for programs that write through
package:twk/cli.dart: a FakeCliTerminal that captures what is written and replays what is typed, to hand aCli, orCli.runthrough itsopen:, in place of the process's terminal; and theFakeClockit can be timed by. - twk_test
- Testing widgets of the twk package:
testTwkruns a test with aTwkTester, which runs the app on a terminal in memory under aFakeClock, delivers input as the bytes a terminal sends and reads the screen back through the emulator (Vt), which matchers such ascontainsLineandmatchesScreenmatch;screenFramesplays a program's writes to a terminal, a recording's, through it, a screen a write. Finders (find) look for the app's widgets, and the tester records its frames (RecordedFrame). What only real time brings (a process, a socket, a file) is waited for with a bound bywaitUntilandwaitFor; a program a test runs in a process of its own is compiled once, and kept for the runs after, bycompiledProgram, and started bystartProcessorrunProcess, which end it, and withgroupwhat it started, when the test ends, however it ends. - vt
- A small but strict terminal emulator used as the test oracle for the presenter. It knows nothing about the core's buffers: it only consumes bytes, like a real terminal, and models the behaviours that cause artifacts in practice:
- vt_terminal
- A terminal backend in the inline mode whose output goes into the Vt emulator as a normal screen with a scrollback, below lines printed before the app ran: what a user would see, history included.