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: testTwk runs your widget under runApp'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, click and resize, 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, and matchesScreen for 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 Shot of 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, FakeClock on 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 a Cli, or Cli.run through its open:, in place of the process's terminal; and the FakeClock it can be timed by.
twk_test
Testing widgets of the twk package: testTwk runs a test with a TwkTester, which runs the app on a terminal in memory under a FakeClock, delivers input as the bytes a terminal sends and reads the screen back through the emulator (Vt), which matchers such as containsLine and matchesScreen match; screenFrames plays 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 by waitUntil and waitFor; a program a test runs in a process of its own is compiled once, and kept for the runs after, by compiledProgram, and started by startProcess or runProcess, which end it, and with group what 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.