twk_test 0.3.0
twk_test: ^0.3.0 copied to clipboard
Tests for twk apps: the real app on a terminal in memory under a fake clock, input as a terminal's bytes, the screen read by an emulator.
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.