term-vt

Terminal (VT/ANSI) emulation: escape-sequence parser and cell-grid screen model, built for testing terminal apps.

term-vt can be used as an in-process emulator core. Feed bytes from a terminal UI and assert on the screen a user would see:

require "term-vt"

screen = Term::VT::Screen.new(rows: 5, cols: 80)
screen.feed(File.read("spinner_success.bin").to_slice)

screen.text.should eq("[\u{2714}] Loading done")
screen.contains?("Loading").should be_true
screen.cursor.should eq({row: 1, col: 0})

It also includes a POSIX PTY-backed black-box harness for driving real terminal programs end to end:

session = Term::VT::Session.spawn("sh", ["-c", "printf 'ok\\n'"])
session.wait_for("ok", deadline: 5.seconds)
session.screen.text.should eq("ok")
session.wait_exit(deadline: 5.seconds).success?.should be_true
session.close

CLI

Build the binary with shards build, then use bin/term-vt to drive any CLI or TUI from the shell without writing Crystal code.

Global flags: --rows N (default 24), --cols N (default 80), --timeout SPAN (default 10s, accepts 500ms, 5s, 1m), --styled, --quiet, and --reflow. --quiet suppresses stdout snapshot emission; failure diagnostics still go to stderr. --reflow enables soft-wrap resize reflow on the primary screen and scrollback (default remains truncate/pad).

Exit codes are a public contract:

Examples:

bin/term-vt run --expect "ready" --expect-exit 0 -- sh -c 'printf ready'
bin/term-vt snapshot --rows 10 --cols 40 -- sh -c 'printf hi'
bin/term-vt snapshot --golden spec/fixtures/screen.txt --update -- my-tui --demo
bin/term-vt script examples/shell.tape

Tape DSL

Tapes are line-based. # starts a comment outside double-quoted strings. Strings must be double-quoted and support Crystal-style escapes such as \n, \t, \e, \", \\, \x21, and \u{2713}. A tape has exactly one run; rows, cols, and reflow may appear before it, and every action after that runs against the same session. wait and idle always require explicit deadlines.

rows 24
cols 80
reflow
run vim --clean -u NONE
wait "~" 5s
idle 50ms 5s
type "iHello"
press escape
press enter
expect "Hello"
expect-not "Error"
snapshot out.txt
snapshot
resize 40 120
send-exit
expect-exit 0

Supported directives:

API

• Term::VT::Parser is a stateful VT/ANSI byte parser. It accepts feed(String) and feed(Bytes) and calls a Term::VT::Performer.
• Term::VT::Screen includes Performer and maintains a cell grid, primary and alternate buffers, scrollback, cursor state, current style, title, bell count, and a bounded unhandled debug list.
• Term::VT::PTY.open(rows, cols) allocates a POSIX master/slave PTY pair, applies the initial winsize, supports resize, and closes both ends idempotently.
• Term::VT::Session.spawn(command, args, rows:, cols:, reflow:, env:) starts a child process attached to a controlling TTY, pumps PTY output through a reader fiber into a mutex-guarded Screen, and provides send, press, type, mouse/paste/focus input helpers, wait_for, wait_idle, wait_exit, resize, and close.
• Term::VT::Keys.sequence(:up) exposes the harness key-name table used by Session#press.
• Term::VT::Mouse.encode(...) encodes mouse events for the wire format (SGR or legacy X10) used by Session mouse senders.
• Term::VT::Width.of(char) returns terminal cell width 0, 1, or 2.
• Term::VT::Style, Term::VT::Color, and Term::VT::Cell are value structs used by the grid and snapshot APIs.

Useful screen methods:

screen = Term::VT::Screen.new(rows: 24, cols: 80, reflow: false)
screen.feed(bytes_or_string)  # => self
screen.row_text(0)            # visible row, trailing whitespace trimmed
screen.rows_text              # Array(String)
screen.text                   # rows joined with newlines, trailing blank rows trimmed
screen.snapshot               # exact padded grid
screen.styled_snapshot        # run-length style rendering
screen.cell(row, col)         # Term::VT::Cell
screen.find("Done")           # {row: Int32, col: Int32}?
screen.contains?("Done")      # Bool
screen.scrollback_text        # Array(String)
screen.reflow?                # Bool — soft-wrap resize reflow enabled?
screen.unhandled              # bounded debug list for skipped sequences
screen.mouse_tracking         # MouseTracking: Off / X10 / Normal / Button / Any
screen.mouse_encoding         # MouseEncoding: Default / Utf8 / Sgr / Urxvt
screen.focus_reporting?       # Bool (?1004)
screen.bracketed_paste?       # Bool (?2004)

Resize contract: default (reflow: false) truncates/pads the grid and clamps the cursor. With reflow: true, resize re-wraps the primary buffer and scrollback at the new width (soft-wrapped runs join; hard newlines never do), never reflows the alternate screen, and restores the cursor to its logical character offset (clamped to the end of the logical line when the old position was inside trailing blanks that joining stripped).

Session input helpers (coordinates are 0-based, matching cursor / find):

session.mouse_down(row, col, MouseButton::Left)
session.mouse_up(row, col, MouseButton::Left)
session.click(row, col, MouseButton::Left)       # down + up, one mode snapshot
session.mouse_move(row, col, MouseButton::Left)  # motion (bit 32; needs ?1002/?1003)
session.scroll(row, col, MouseButton::WheelUp)   # wheel press (WheelUp / WheelDown)
session.paste(text)                              # bracketed when ?2004 is on
session.focus(true | false)                      # \e[I / \e[O

Mouse senders and focus fail loud: they raise ArgumentError when the live screen has not enabled the corresponding mode (mouse_tracking off, or focus_reporting? false). mouse_move is stricter still — it requires button-event (?1002) or any-event (?1003) tracking; X10/Normal alone raise. That is a test bug — clicking into an app that never enabled mouse mode. paste is the exception: it degrades to a raw send when bracketed paste is off.

Wire encoding follows the live screen: only mouse_encoding.sgr? changes the encoder (SGR sequences). Default, Utf8, and Urxvt all send legacy X10 bytes (coordinates capped at 223). Utf8 / Urxvt are still tracked so tests can assert the app requested those modes.

Black-box Testing

Session is intended for integration tests that need a real terminal device: raw-mode behavior, tty? checks, shell programs, readline-style DSR queries, or key sequences flowing through a PTY.

session = Term::VT::Session.spawn("sh", ["-i"],
  rows: 24,
  cols: 80,
  env: {"PS1" => "$ ", "TERM" => "xterm"})

begin
  session.wait_for("$", deadline: 5.seconds)
  session.type("printf hello")
  session.press(:enter)
  session.wait_for("hello", deadline: 5.seconds)
  session.wait_idle(settle: 50.milliseconds, deadline: 5.seconds)
  session.screen.contains?("hello").should be_true
ensure
  session.close
end

Every wait primitive polls with a deadline and raises Term::VT::TimeoutError with the current screen.snapshot in the message. wait_idle uses the screen change counter rather than comparing grids.

The PTY/session harness is POSIX-only. It uses the rung-2 controlling-TTY strategy from plan 023: a small vt-ctty shim built into .term-vt/bin/ that runs setsid, attaches the PTY slave with TIOCSCTTY, sets the foreground process group, then execvps the requested command. Rung 1 (Process.new with the slave as stdio and no setsid) was rejected because it passed tty and stty size but did not deliver Ctrl-C as terminal signal semantics on macOS.

PTY-dependent specs mark themselves pending when PTY allocation or helper build support is unavailable.

Supported Keys

Session#press accepts these names:

Supported Sequences

Unknown or unsupported sequences are consumed silently and appended to screen.unhandled when they are useful for debugging. The list is capped at 100 entries.

Snapshot Format

screen.snapshot is the exact grid contract for golden files: every row is present, every row is padded to screen.cols cells (not codepoints), and rows are joined by \n. Styling is ignored. Cells with attached zero-width extras emit base char then extras, so a row may contain more codepoints than cols while still covering exactly cols cells.

screen.styled_snapshot is a run-length style contract. It emits one line per visible row, trims trailing default blank cells, and writes segments as:

{attrs}text{attrs}more

The default style is {}. Attribute names are emitted in this order: bold dim italic underline blink inverse hidden strike fg=<n|#rrggbb> bg=<n|#rrggbb>.

Example:

{bold fg=2}Done{} in {fg=#010203}3s

extras join their cell's segment text (marks stay inside the same style run as the base character).

find / contains? are exact byte/codepoint matches against the stored form — there is no Unicode normalization. Assertions must match the app's emitted form (e.g. NFD "e\u{0301}" does not match NFC "é").

Unsupported

These are intentionally out of scope and should be added without changing the public parser/screen split:

• Left/right margins (DECSLRM) and rectangle operations.
• Highlight mouse tracking (?1001) and DEC locator mode (left in unhandled).
• Interpreting inbound mouse sequences from the child (events only flow child-ward from Session).
• Grapheme clustering (UAX #29): zero-width marks attach to the preceding cell, but ZWJ sequences occupy multiple cells and VS16 does not widen.
• Windows/ConPTY (core compiles on Windows; PTY harness POSIX-only — see plan 033 findings).