tuitest

package module
v0.3.2 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 15, 2026 License: MIT Imports: 25 Imported by: 0

README ¶

tuitest

Go reference

A headless testing harness for terminal programs in Go.

every keypress, click, scroll and assertion above is tuitest driving the real program, and the pane below it is tuitest's own trace of what it sent

You bring a terminal program, any language, any framework, and a tape script or a Go test function. tuitest gives back a real pseudo-terminal to run it on, a VT emulator that turns its output into a grid of cells, waits that block on screen state instead of sleeping, and assertions that compare what a user would see.

The command line and the Go package are two ways in, and neither is the lesser one. tuitest run login.tape tests a TUI with no Go anywhere; tuitest.StartT does the same thing from a test function. Both drive the same Terminal, so a tape and a Go test fail for the same reasons and print the same screens.

Quick start

You need a Unix-like OS that can open PTYs (/dev/ptmx) and Go 1.26 or newer to install. The minimum moved from Go 1.25 to 1.26 because the emulator module, tuios.dev/vt, needs it. go get raises the go line of your go.mod to 1.26.0. Windows deliberately fails to build; see docs/limits.md.

From the command line
go install github.com/Gaurav-Gosain/tuitest/cmd/tuitest@latest

# check this machine can run a TUI at all; exits 3 if not, so it gates CI
tuitest doctor

# look at what a program draws, asserting nothing
printf 'hello from tuitest\n' > note.txt
tuitest snap --size 60x8 -- less note.txt

# write down what should happen as a tape
cat > first.tape <<'EOF'
Set Size 60 8
Spawn less note.txt
Wait /hello from tuitest/
Key q
ExpectExit 0
EOF

# run it: silent and exit 0 when every assertion holds,
# the screen and a non-zero exit code when one does not
tuitest run first.tape

From there the loop is snap to look, record or an editor to write a tape, run in CI, replay to watch a failing tape, and fuzz to go looking for trouble:

tuitest record -o login.tape -- ./myapp   # drive it by hand, Ctrl+] to stop
tuitest replay login.tape                 # watch the tape run
tuitest fuzz --duration 30s --corpus ./corpus -- ./myapp

examples/tapes has a runnable tape for every verb of the language.

From Go
go get github.com/Gaurav-Gosain/tuitest
package myapp_test

import (
	"testing"
	"time"

	"github.com/Gaurav-Gosain/tuitest"
)

func TestGreeting(t *testing.T) {
	// Any argv works; this one is a tiny program that asks for a name.
	prog := []string{"sh", "-c", `printf 'name? '; read name; printf 'hello, %s\n' "$name"`}
	term := tuitest.StartT(t, prog, tuitest.WithSize(40, 5))

	if err := term.WaitForText("name?", 5*time.Second); err != nil {
		t.Fatal(err)
	}
	if err := term.SendKeys("gopher", tuitest.Enter); err != nil {
		t.Fatal(err)
	}
	if err := term.WaitForText("hello, gopher", 5*time.Second); err != nil {
		t.Fatal(err) // the error carries the screen as it was
	}
	term.AssertGolden(t, "greeting") // compares against testdata/greeting.golden
}

StartT registers Close through t.Cleanup, fails the test if the spawn itself fails, and writes the last 32KB of PTY traffic to t.Log if the test fails. Record the golden once with UPDATE_GOLDEN=1 go test ./..., then review it as part of the diff. It holds name? hello, gopher: the PTY does not echo input, so the screen shows only what the program drew (see docs/limits.md).

The full Go surface is in docs/api.md, and every example in example_test.go runs under go test and is shown on pkg.go.dev.

What it does

  • Spawns the program under test on a real pseudo-terminal through xpty, so isatty is true, TERM means something, and the program takes its interactive code path instead of the piped-output one.
  • Interprets everything the program writes with a full VT emulator: cursor motion, scroll regions, SGR styling, the alternate screen, wide runes, scrollback, mouse mode state, OSC 133 semantic markers.
  • Blocks on conditions rather than sleeping. WaitForText, WaitForMatch, WaitFor and WaitForOutput are woken by the output pump the moment new bytes are interpreted. They do not poll. Only a quiet window, as in WaitStable, sets a timer, for the moment it ends. WaitForStable also waits for the frame the condition matched to finish drawing.
  • Never shows a half-drawn frame from a program that uses synchronized output (mode 2026, which every Bubble Tea v2 program does): while an update is open, the screen the waits and Screen see is the last complete frame, as on a real terminal.
  • Reports a wait failure as a *TimeoutError or *ClosedError carrying the full screen and the last 4KB of PTY traffic, so a CI log shows what was on screen instead of a bare "timeout".
  • Sends named keys as typed Key constants, so a misspelled key is a compile error; Ctrl('b') builds a control byte, Alt(k) holds Alt, and Mod(Up, ModCtrl) holds modifiers on a named key in the xterm form. Keys follow the keyboard modes the program set, as they do on a real terminal: the cursor key mode (DECCKM), the kitty keyboard flags and modifyOtherKeys.
  • Sends mouse events as SGR (mode 1006) sequences, and pastes as bracketed paste (mode 2004), which is the code path a program handles differently from typed text and usually tests less.
  • Resizes the PTY so the child receives a genuine SIGWINCH, and resizes the emulator grid to match in the same call.
  • Tears the child down by process group: the child is started under setsid with the PTY as its controlling terminal, and Close signals the whole group, plus any descendant that left it with setsid, with SIGTERM then SIGKILL, so a multiplexer's daemon and its pane processes do not survive the test. Close returns an error naming anything that did, and StartT fails the test with it.
  • Reports whether the program restored the terminal. TermState.Dirty() is true when the alternate screen, mouse tracking (modes 9/1000/1001/1002/1003), bracketed paste, focus reporting, or a hidden cursor is left set on exit.
  • Separates signal death from a non-zero exit through ExitStatus, which ExitCode alone flattens to -1, and treats SIGTERM, SIGKILL, SIGINT, SIGHUP and SIGPIPE as routine teardown rather than a crash.
  • Writes golden files in two encodings: plain text, and a styled encoding of each row's text followed by indented attribute runs, diffed in-process with a line LCS so nothing shells out to system diff.
  • Runs tape scripts, a line-oriented language of 20 verbs covering exactly the harness primitives, with parse errors reported by file, line, column, and a caret under the offending token.
  • Records a live session into a tape: it connects the program to your terminal, decodes the input you send back into Key and Type commands, and chooses a Wait on new distinctive screen text wherever the screen settled, falling back to WaitStable and never emitting Sleep unless asked.
  • Replays a tape onto your terminal so you can watch it, rendering assertion failures as two screens side by side with a | against every differing row.
  • Fuzzes any terminal program with structured input (text mixing ASCII, CJK, emoji and combining marks; coherent mouse drags; degenerate resizes; malformed UTF-8 and truncated escape sequences), detects crashes, hangs, dirty terminals, inconsistent screen state and RSS growth, and minimises each finding by delta debugging into a tape that replays it.
  • Diagnoses the environment with tuitest doctor: PTY allocation, platform, TERM, size handling, emulator capabilities, and the conditions that make a suite flaky. It spawns nothing and writes nothing.
  • Exits with codes CI can branch on: 0 pass, 1 assertion failed, 2 bad usage or malformed tape, 3 harness error, 4 wait timed out, 5 snap saw an empty screen.

Design goals

  • Black box. The program under test is a binary behind a PTY. Nothing in the harness knows about Bubble Tea, ratatui, ncurses, or any framework, so the same test works against a Go TUI, a C one, or vim.
  • Deterministic. Waits block on conditions and are woken by output, so a test runs as fast as the program does and does not get slower or flakier on a loaded runner. Sleep exists in the tape language and -strict rejects it.
  • Legible failure. Every failure carries the screen. A timeout names what it waited for and for how long; a failed Expect finds the closest line and marks the first differing column; a parse error points at the token.
  • Replaceable parts. The emulator, the PTY layer, the tape language and the CLI are separate packages with narrow seams, and the emulator in particular is internal on purpose so swapping it is not a breaking change.
  • Honest. The docs state which waits are exact conditions and which are heuristics, which platform is unsupported and why, and which emulator version a run uses. Performance numbers carry the machine they were measured on. See docs/limits.md.

Architecture

flowchart TB
  subgraph Bring["Bring your own"]
    PROG[program under test<br/>any binary, any language]
    TAPE[tape file<br/>or a Go test function]
  end

  subgraph CLI["cmd/tuitest + internal/cli"]
    REG[cobra command tree<br/>run, record, replay, snap, fuzz, doctor]
  end

  subgraph Lang["tape"]
    PARSE[parse<br/>lexer, positions, verb suggestions]
    PLAY[player<br/>executes commands, asserts]
    REC[recorder<br/>session to tape, timing policy]
  end

  subgraph Core["tuitest root package"]
    TERM[Terminal<br/>waits, input, snapshots, goldens]
  end

  subgraph Low["internal"]
    PTY[ptyproc<br/>spawn, pump, resize, group teardown]
    EMU[emu.Emulator<br/>twelve-method interface]
    VT[tuios.dev/vt<br/>VT interpreter]
  end

  FUZZ[fuzz<br/>generator, detectors, shrinker]
  VTGEN[fuzz/vtgen<br/>deprecated, forwards to tuios.dev/vt/vtgen]

  TAPE --> PARSE --> PLAY --> TERM
  REG --> PLAY
  REG --> REC --> PARSE
  REG --> FUZZ --> TERM
  TERM --> PTY --> PROG
  PROG --> PTY --> TERM --> EMU --> VT
  VTGEN -.-> VT

Only the root package is public API; internal/emu and internal/ptyproc are not importable, which is deliberate. The emulator is the module tuios.dev/vt, behind internal/emu. The emulator choice is not part of the contract, so replacing it is not a breaking change.

The importable library has five direct dependencies (tuios.dev/vt for the emulator, charmbracelet/ultraviolet for the cell model, charmbracelet/x/ansi for color parsing, charmbracelet/x/xpty for PTY allocation, charmbracelet/x/term for the recorder's raw mode). spf13/cobra and charmbracelet/fang are in go.mod for the command line, but nothing outside cmd/tuitest and internal/cli imports them, so they never reach a consumer's binary.

ptyproc owns process and PTY lifetime and knows nothing about screens; Terminal owns screens and waits and knows nothing about exec. That split is what lets the fuzzer drive a Terminal while watching the process from outside it, using Progress() for liveness and ExitStatus() for cause of death.

The fuzz package generates tape.Command values, not bytes. Candidates replay through the same player tuitest run uses, which is what makes a minimised reproduction trustworthy: it is not a description of what the fuzzer did, it is the same execution path.

fuzz/vtgen points the other way. It generates the bytes a program writes, by grammar rather than by byte, for testing whatever parses them. It is deprecated and forwards to tuios.dev/vt/vtgen, which anything with a VT parser can import. See docs/fuzzing.md.

How a tape becomes assertions

flowchart LR
  T[tape file] --> P[parse<br/>one Command per line]
  P --> R{verb?}
  R -- Spawn --> S[ptyproc.Start<br/>setsid, PTY, pump goroutine]
  R -- "Type / Key / Mouse / Paste / Raw" --> W[Terminal.write<br/>marks lastInput]
  R -- "Wait / WaitStable / Expect" --> C[waitLoop<br/>cond.Wait on the screen]
  R -- Snapshot --> G[golden compare<br/>line LCS diff]
  S --> PT[PTY master]
  W --> PT
  PT --> PUMP[pump goroutine<br/>32KB reads]
  PUMP --> E[emu.Write<br/>cell grid updated]
  E --> B[cond.Broadcast]
  B --> C
  C --> G

Every wait shares one loop. It holds the terminal lock, evaluates its condition, and blocks on a sync.Cond. The output pump broadcasts after each chunk is interpreted, and so do a resize, input reaching the program, the exit and an emulator panic. A screen condition cannot change between those events, so there is no poll. A timer runs only for a moment the clock alone can bring: the end of a quiet window in WaitStable and WaitForStable, the expiry of a synchronized update's hold, and the deadline. Conditions build a screen snapshot only if they need one, so a cheap condition does not pay to rebuild the grid on every write during a heavy burst, and a snapshot is reused until the grid changes, so a wait on a quiet screen costs next to nothing.

WaitStable is the one heuristic here, and it is easy to misuse. It measures its quiet window from the later of the last output byte and the last input tuitest sent, which stops it from reporting the pre-keystroke screen as stable, and it never settles before the program's first byte, but a program that takes longer than the interval (150ms by default) to react to input is still reported stable early. WaitForOutput is the primitive for "wait until the program reacts to what I just sent", and WaitForStable for "wait until this is on screen and the frame has finished drawing"; prefer waiting on the content you expect whenever you know it.

What it looks like

Every recording below drives the real binary against a real program: less paging this repository's README, vim opening a file from scripts/, and the deliberately broken fixture in testdata/buggytui. The recording at the top of this page drives lazygit the same way. The tapes that produce them are in scripts/demo and regenerate with scripts/demo/record.sh.

tuitest snap runs vim on a tape file at 84 columns and prints the screen as text, then runs the same file at 52 columns where the comment lines wrap and vim truncates the filename in its status line
a tape testing a program with no Go anywhere, and what a stale assertion prints when it fails
snap printing what a program draws, then the same program at a second width
fuzzing a fixture that panics on F5, minimised to a two-line tape that replays it

Command line

tuitest run         play a tape script against a program            # exit 0 to 4
tuitest record      drive a program by hand and write a tape        # Ctrl+] to stop
tuitest replay      play a tape onto this terminal so you can watch # -step, -speed
tuitest snap        spawn, wait for quiet, print the screen         # asserts nothing
tuitest fuzz        drive with randomised input, report what breaks # writes tape repros
tuitest doctor      report on the environment tests will run in     # spawns nothing
tuitest completion  print a bash, zsh, fish or powershell script    # cobra generated
tuitest version     print the tuitest version                       # module or -ldflags version
tuitest help        show help for a command                         # tuitest help run

Every command has its own help with examples (tuitest help run). Commands, help and completion are built on spf13/cobra and rendered by charmbracelet/fang; completion is resolved by calling the binary back rather than from a script baked at build time, so it cannot fall out of step with the commands. Flags take either spelling: -size and --size both work. run, snap and doctor accept -json and print one object to stdout: run reports status, a kind naming the exit code, durationMs, and the full error text including the screen at the moment of failure.

A flag beats the tape's own Set line for the same setting, which is what makes tuitest run -size 120x40 login.tape useful for checking a layout at a second size without editing the file; -env accumulates instead, since environment entries add up. Put -- before the program in snap, record and fuzz so its own flags are not read as tuitest's. run -strict rejects Sleep, which is a cheap way to keep a suite honest. An unknown subcommand or a misspelled tape verb gets a nearest-match suggestion rather than a bare rejection.

Exit codes are the contract with CI, separating "your program is wrong" from "the tool could not run it":

Code Meaning
0 every assertion passed
1 an assertion failed, the program exited before the tape was done with it, or fuzz found something
2 bad usage, or a tape that would not parse
3 harness error: no PTY, a program that would not start, an unreadable tape or golden
4 a wait timed out
5 snap only: the program drew nothing

The full flag reference for every subcommand is in docs/cli.md.

The tape language

A tape is line oriented, one command per line, and a line starting with # is a comment.

Set Size 40 10
Set Term xterm-256color
Spawn ./myapp
Wait /ready/ +Screen @5s
Type hello
Key Enter
Wait /you said hello/ @5s
Snapshot after-hello +Styled
Resize 60 20
Mouse Press Left 10 5 +Ctrl
Raw "\x1b[1;2;3m"
ExpectExit 0

The 20 verbs are Set, Spawn, Type, Key, Wait, WaitStable, WaitOutput, WaitPrompt, WaitCommand, Expect, ExpectExit, Snapshot, Resize, Mouse, Paste, Raw, Focus, Hide, Show and Sleep, and examples/tapes has a runnable tape using each of them. Wait and Expect take a /regex/ and a +Screen or +Line scope, and every verb that waits takes an @timeout such as @5s; an argument a verb does not take is a parse error. Paste and Raw take a Go-quoted string, which is what lets them carry arbitrary bytes including malformed UTF-8 and embedded escape sequences, and a Spawn or Set argument containing a space is written the same way. The grammar, the Set keys, and the validation limits are in docs/tape.md.

A recording never loses input. Every input sequence is decoded by a registered protocol (the legacy keys, xterm modifyOtherKeys, the kitty keyboard protocol, the X10, SGR, SGR-pixel and urxvt mouse encodings, bracketed paste and focus reporting) or, failing that, captured verbatim as a Raw command that replays byte for byte. So a tape is a faithful replay whether or not a decoder exists for everything in it, and terminal replies to capability queries are never mistaken for keystrokes. See docs/input-protocols.md for the guarantees, the round-trip property, what happens when replay negotiates different keyboard modes than the recording did, and how to add a protocol.

Fuzzing a TUI

tuitest fuzz drives a program with randomised but structured input and reports seven kinds of finding: crash, hang, dirty-terminal, screen-inconsistent, memory-growth (Linux only, off unless -max-memory-growth is set), replacement-char (off unless -detect-replacement-chars is set), and invariant. A clean exit is never a finding, because the fuzzer sends keys that legitimately quit a program and treating that as a bug would make every run a false positive.

dirty-terminal is the highest-value check in practice: it is a real bug class, it is common, and unlike the others it has almost no false-positive surface, because a program that turned a mode on is unambiguously responsible for turning it off. Hang detection is the one heuristic, and it is tuned to stay quiet rather than to catch everything.

invariant is the only oracle that knows anything about your program. Pass func(tuitest.Screen) error closures in fuzz.Options.Invariants and a session can find that a status bar disappeared or a modal was left open, not just that the program died. A violation is an ordinary finding, so the shrinker minimises it like any other, and the report names the command after which the property first failed rather than the one where the checker noticed. It is checked only after a settle, because a screen caught mid-redraw fails a reasonable invariant. There is no CLI flag: a tape file cannot carry a Go closure.

replacement-char reports U+FFFD reaching the screen, which means the program mangled a byte sequence between reading it and drawing it. It is off by default and goes quiet for a run as soon as the fuzzer sends malformed UTF-8, because against malformed input a replacement character is the correct output rather than a bug. Both of these are documented with their limits in docs/fuzzing.md.

Every finding is minimised by delta debugging and written as an ordinary tape:

# crash: program killed by SIGABRT
# found by tuitest fuzz at iteration 6, whose own seed is 13064056694810536104:
# --seed 13064056694810536104 --iterations 1 with the same generation flags regenerates the unminimised input
# minimised from 31 commands to 3
#
# replay with: tuitest run <this file>

Spawn htop
Resize 1 1
Raw "hel"

# --- assertion (not replayed by tuitest fuzz) ---
# The bug: this program should still exit cleanly after the input above.
ExpectExit 0

That is a real reproduction, minimised from 31 commands to 3: a buffer overflow in htop 3.5.1, caught by glibc's fortify check. With -corpus dir findings are saved there and replayed first on the next run, so a fix is confirmed when the corpus stops reproducing. See docs/fuzzing.md.

Performance

Measured on 2026-10-08 on an Intel i7-10700 (16 threads, Linux), 80-column grid, five runs of go test -run '^$' -bench 'EmulatorPlainLines|EmulatorStyledLines' -benchtime 3s ., reproducible from bench_test.go in the root package. The machine had a load average of about 29, so these figures are wall time under load and a lower bound. The audit of this release measured plain lines at 51 to 53 MB/s at a load average of about 5. That figure is not reproduced here.

Workload Lines per second Bytes per second
Plain 80-column text lines 360,000 to 460,000 29 to 37 MB/s
Same with an SGR change per line 190,000 to 225,000 19 to 22 MB/s

The emulator is the only component in the read path that scales with output volume, and it is single-threaded by construction: a VT interpreter is a state machine over an ordered byte stream, so adding concurrency cannot make this faster. A program that emits far more than this feels PTY backpressure rather than losing data, so heavy-output tests need timeouts sized for the volume, not for the harness.

Waits themselves cost nothing while idle: they block on a condition variable and are woken by the pump, so a suite's wall-clock time is the program's own latency. A wait with no output to read makes no wakeups.

Limitations

The full list, with the reasoning, is in docs/limits.md. The ones most likely to matter:

  • Unix only, and it fails to build on Windows on purpose. There is no ConPTY backend and no process group to signal, so teardown could not keep its promise; the package produces a named compile error rather than building into something that looks supported and leaks every grandchild. Use WSL or a Unix runner.
  • WaitStable is a heuristic and always will be. A program slower than the stabilize interval to react to input is reported stable early. Wait on content when you know it.
  • The VT emulator is the version of tuios.dev/vt in go.mod. A fix in tuios reaches tuitest only when that version moves. Move it on purpose and review the goldens that move with it.
  • Screen.Line returns one physical row and does not de-wrap, so text that soft-wrapped at the right margin does not match as one string.
  • The PTY does not echo input or turn Ctrl+c into SIGINT. A TUI never notices, but a line-oriented program's typed input is not on screen, and Ctrl+c does not interrupt it.
  • Mouse mode 1005 (UTF-8 coordinates) is not decoded as itself. It is indistinguishable from X10 by construction, so it is read as X10 and the coordinates on the Mouse line are wrong above column 95. The bytes still replay exactly, so this costs readability rather than fidelity.
  • Two of the fuzzer's own tests can be flaky under load. They assert that a minimised reproduction re-reproduced on the confirmation replay, which is a property the fuzzer does not guarantee: confirmation drives a real program through a real PTY. The macOS failures came from a harness bug that is fixed; whether any remain on Linux has not been measured. See docs/limits.md.
  • The fuzzer's two oracles are gated, and each gate costs coverage. The replacement-character check goes quiet for a whole run once one malformed byte has been sent, which with the default generator is almost immediately. User-supplied invariants are judged only at a settle, so a violation that repairs itself before the end of an iteration is never seen. Both gates were chosen over the alternative because a fuzzer that reports things that are not bugs trains you to stop reading it.
  • Fuzz generation is blind. There is no coverage instrumentation of the program under test, so input comes from a structural model rather than being steered toward new code paths. It finds shallow bugs quickly and deep ones only by luck.

Comparison

teatest (charmbracelet/x/exp/teatest) drives a Bubble Tea program in process, which is fast and lets it reach into the model, but it only works for Bubble Tea and it tests the program rather than the terminal: no PTY, so it cannot tell you what a real terminal would show. tuitest is the opposite trade, a black box behind a real PTY, slower, with no access to internal state. If you write Bubble Tea and want fast unit tests of your update loop, use teatest; if you want to know what the user sees, or you do not control the source, use this.

expect and its descendants (expect, pexpect, go-expect) also drive a PTY and are excellent at line-oriented conversations: log in, wait for a prompt, send a password. They match against the byte stream, which is exactly wrong for a full-screen program, because a TUI's bytes are cursor movements and partial redraws that never contain the final text in reading order. tuitest interprets those bytes into a screen first, which is the whole difference.

VHS records terminal sessions to GIFs and has a tape format that inspired this one. It is a demo tool, not an assertion tool; tuitest's tape language covers the harness primitives and produces golden text, not video.

Extending

Each seam is narrow on purpose:

  • Swap the VT emulator (implement internal/emu.Emulator, twelve methods).
  • Add a CLI subcommand (one *cobra.Command added in newRootCommand; help, completion and typo suggestions follow automatically).
  • Add a tape verb (one Kind, one Verb() case, one parse case, one player case, one printer case).
  • Drive the harness from your own runner (import the root package; tape and fuzz are both ordinary callers of *Terminal).
  • Add project-specific helpers alongside tuiosx rather than in the core.

See docs/architecture.md and docs/extending.md.

Tests

go build ./...
go vet ./...
go test -race ./...

The default suite is hermetic: it spawns a small Go echo-TUI fixture under testdata/echotui, a deliberately buggy fixture with individually selectable bugs under testdata/buggytui, and a plain sh. Nothing external is required. CI runs the same commands on Linux and macOS; see .github/workflows/test.yml.

Everything that parses input tuitest does not control has a fuzz target, among them FuzzParse and FuzzResolveKey for the tape language, the FuzzDecode* and FuzzRecorder* targets for recorded input, and FuzzEmulatorScreen and FuzzEmulatorScript for the emulator (grep -r 'func Fuzz' lists them all). Their seed corpora live in testdata/fuzz directories, so go test runs them as ordinary unit tests and they act as regression guards with no fuzzing session. To actually fuzz:

go test -run '^$' -fuzz FuzzParse ./tape
go test -run '^$' -fuzz FuzzEmulatorScreen .

Two suites are opt-in because they need a multiplexer. TUITEST_TUIOS=1 go test -race ./tuiosx/... runs the tuios acceptance tests, and the examples under examples/tuios skip themselves unless a tuios binary is found through TUIOS_BIN or PATH. They are worth reading as realistic usage even if you never run them: boot and window management, a control plane driven over a unix socket with a TUI later attached to the same session, and a flood-plus-resize stress test.

Project

License

MIT. See LICENSE.

The VT emulator, tuios.dev/vt, is part of tuios, which is also MIT licensed by the same author.

Documentation ¶

Overview ¶

Package tuitest is a headless testing harness for terminal programs. It drives a program under test through a real pseudo-terminal, interprets its output with a VT emulator, and lets tests assert on the resulting screen as a grid of cells rather than as a raw byte stream.

The typical flow: Start (or StartT under go test) spawns the program, SendKeys and Type drive input, the WaitFor family synchronizes on screen state without sleeping, and Snapshot / AssertGolden capture the result. Close (registered automatically by StartT) tears down the whole process group.

Example ¶

Start a program, type into it, wait for its answer, and read the screen.

"gopher" is not on the screen. tuitest turns the PTY's echo off before the program starts, so the screen holds only what the program drew, and a line-oriented program that relies on the terminal to echo its input shows none. A TUI draws its own input, so this only shows up with programs like this one. See docs/limits.md.

package main

import (
	"fmt"
	"time"

	"github.com/Gaurav-Gosain/tuitest"
)

// greeter is a tiny interactive program: it asks for a name and answers.
var greeter = []string{"sh", "-c", `printf 'name? '; read name; printf 'hello, %s\n' "$name"`}

func main() {
	term, err := tuitest.Start(greeter, tuitest.WithSize(40, 5))
	if err != nil {
		fmt.Println(err)
		return
	}
	defer term.Close() //nolint:errcheck

	if err := term.WaitForText("name?", 5*time.Second); err != nil {
		fmt.Println(err)
		return
	}
	_ = term.SendKeys("gopher", tuitest.Enter)
	if err := term.WaitForText("hello, gopher", 5*time.Second); err != nil {
		fmt.Println(err)
		return
	}
	code, _ := term.WaitExit(5 * time.Second)

	fmt.Println(term.Snapshot())
	fmt.Println("exit", code)
}
Output:
name? hello, gopher
exit 0

Index ¶

Examples ¶

Constants ¶

View Source
const CastDirEnv = "TUITEST_CAST_DIR"

CastDirEnv names the environment variable that turns on recording for StartT and StartProgramT. When it is set, a terminal whose test fails is written to that directory as an asciicast v2 file. See WithCastDir.

View Source
const DefaultStabilizeInterval = 150 * time.Millisecond

DefaultStabilizeInterval is the quiet window WaitStable uses unless overridden.

View Source
const DefaultWriteTimeout = 10 * time.Second

DefaultWriteTimeout is how long input may wait for the program to read it, unless WithWriteTimeout sets another limit.

View Source
const StartTLogTail = 32 * 1024

StartTLogTail is how many bytes of PTY I/O StartT keeps for the test log.

Variables ¶

View Source
var (
	// ErrTimeout is wrapped by every wait that runs out of time.
	ErrTimeout = errors.New("tuitest: timed out")
	// ErrChildExited is wrapped when the program under test exits before a
	// wait's condition is met, and by input (Type, SendKeys, Paste, SendMouse,
	// Resize) that failed because the program has exited.
	ErrChildExited = errors.New("tuitest: child exited before the condition was met")
	// ErrSemanticMarkers is wrapped by the OSC 133 waits when the terminal was
	// started without WithSemanticMarkers.
	ErrSemanticMarkers = errors.New("tuitest: semantic markers are not enabled (use WithSemanticMarkers)")
)

Sentinel errors for the three ways a wait can fail. Every wait returns an error that wraps one of these, so a caller can branch on the kind of failure without type-asserting the concrete error:

if err := term.WaitForText("ready", time.Second); errors.Is(err, tuitest.ErrTimeout) {
	// the program is merely slow
}
View Source
var ErrEmulatorPanic = errors.New("tuitest: the terminal emulator panicked")

ErrEmulatorPanic is wrapped by every call made on a terminal whose VT emulator panicked while it read the program's output.

Functions ¶

func Diff ¶

func Diff(want, got string) string

Diff returns a compact line-oriented diff of want versus got, the same encoding AssertGolden uses in its failure messages. It is exported so out-of-package golden runners (such as the tape player) can reuse it.

Example ¶

Diff is the line diff AssertGolden prints on a mismatch.

package main

import (
	"fmt"

	"github.com/Gaurav-Gosain/tuitest"
)

func main() {
	fmt.Print(tuitest.Diff("title\nok\n", "title\nfail\n"))
}

func Find ¶

func Find(s Screen, substr string) (col, row int, ok bool)

Find locates the first occurrence of substr on the screen, scanning rows top to bottom, and returns the zero-based cell column and row where it starts. It reports false when no single row contains substr, which includes text that soft-wrapped across two rows.

The column is a cell column, the coordinate SendMouse takes, and not an offset into the row's text. The two differ as soon as anything before the match is not one byte wide: a box-drawing border is three bytes and one cell, a CJK character or an emoji is two cells, so clicking at a byte or rune offset lands to one side of the text.

Types ¶

type Cell ¶

type Cell struct {
	// Rune is the cell's first rune. A cell can hold a whole grapheme cluster,
	// so this is not always the character a user sees: "e" plus a combining
	// acute reports 'e' here. Use Content to compare against text.
	Rune rune
	// Content is the cell's full grapheme cluster: the base rune together with
	// any combining marks, joiners and modifiers that attach to it. It is what
	// Line and Text render, and what a caller should match against. Empty for
	// the continuation column of a wide rune.
	Content string
	// Width is 1 for normal runes, 2 for wide runes, and 0 for the
	// continuation column that follows a wide rune.
	Width int
	// Fg and Bg are the foreground and background colors.
	Fg, Bg        Color
	Bold          bool
	Faint         bool
	Italic        bool
	Underline     bool
	Reverse       bool
	Strikethrough bool
	Blink         bool
	// Conceal reports SGR 8 (hidden). A real terminal draws a concealed cell as
	// a blank, so Line and Text render these cells as spaces; the rune is still
	// available here for a caller that needs to know what was concealed.
	Conceal bool
}

Cell is a single grid cell with its rune and visual attributes.

type ClosedError ¶

type ClosedError struct {
	// Op is the wait that failed, such as "WaitForText".
	Op string
	// Want describes the condition in words.
	Want string
	// ExitCode is the child's exit code, or -1 if it could not be determined.
	ExitCode int
	// Screen is the plain-text screen at the moment of the failure.
	Screen string
	// TailLog is the tail of the mirrored PTY I/O.
	TailLog string
}

ClosedError is returned when the child exits before a wait's condition is met. It unwraps to ErrChildExited.

func (*ClosedError) Error ¶

func (e *ClosedError) Error() string

func (*ClosedError) Unwrap ¶

func (e *ClosedError) Unwrap() error

Unwrap makes errors.Is(err, ErrChildExited) true for every early exit.

type Color ¶

type Color struct {
	// Kind selects which of the remaining fields is meaningful.
	Kind ColorKind
	// Index is the palette entry when Kind is ColorIndexed.
	Index uint8
	// R, G and B are the channel values when Kind is ColorRGB.
	R, G, B uint8
}

Color is a cell color in one of three encodings. Only the fields matching Kind carry meaning; the others are zero.

type ColorKind ¶

type ColorKind int

ColorKind distinguishes the three color encodings a cell can carry.

const (
	// ColorDefault is the terminal's default foreground or background.
	ColorDefault ColorKind = iota
	// ColorIndexed is a palette color 0-255.
	ColorIndexed
	// ColorRGB is a 24-bit true color.
	ColorRGB
)

type EmulatorPanicError ¶

type EmulatorPanicError struct {
	// Op is the call that failed, such as "WaitForText" or "Type".
	Op string
	// During says what the emulator was doing when it panicked, such as
	// "reading the program's output" or "resizing to 80x24".
	During string
	// Value is what the emulator panicked with.
	Value any
	// Stack is the stack of the goroutine that panicked.
	Stack string
	// Chunk is the output the emulator was reading when it panicked. It is
	// empty when the panic came from something other than the output.
	Chunk []byte
	// Screen is the plain-text screen when the emulator panicked.
	Screen string
	// TailLog is the tail of the mirrored PTY I/O.
	TailLog string
}

EmulatorPanicError is returned by every wait, every input call and Resize once the emulator has panicked. It unwraps to ErrEmulatorPanic.

The panic usually happens on the goroutine that reads the program's output, where no test can catch it. Left alone it ends the whole test binary: every other result is lost and no cleanup runs, so the programs the tests started are left running. The terminal recovers it instead, keeps reading the program's output so the program does not block on a full PTY, and stops feeding that output to the emulator, whose state can no longer be trusted. A panic in a resize or in a read of the screen is recovered the same way.

The calls that return no error (Screen, Snapshot, TermState and LastCommandExit) return the state the emulator had when it panicked. They do not read the emulator again.

func (*EmulatorPanicError) Error ¶

func (e *EmulatorPanicError) Error() string

func (*EmulatorPanicError) Unwrap ¶

func (e *EmulatorPanicError) Unwrap() error

Unwrap makes errors.Is(err, ErrEmulatorPanic) true.

type ExitStatus ¶

type ExitStatus struct {
	// Code is the exit status, or -1 when the child died from a signal.
	Code int
	// Signaled is true when the child was killed by a signal rather than
	// exiting on its own.
	Signaled bool
	// Signal is the killing signal when Signaled is true.
	Signal syscall.Signal
}

ExitStatus describes how the child finished.

func (ExitStatus) Crashed ¶

func (s ExitStatus) Crashed() bool

Crashed reports whether the child died in a way that indicates a bug: killed by a fault signal, or exited non-zero. A clean zero exit is not a crash.

func (ExitStatus) String ¶

func (s ExitStatus) String() string

type Key ¶

type Key string

Key is a named key or chord expressed as the escape sequence it sends. Using typed values means a mistyped key name is a compile error, not a silent mismatch at runtime.

const (
	Enter     Key = "\r"
	Tab       Key = "\t"
	Esc       Key = "\x1b"
	Space     Key = " "
	Backspace Key = "\x7f"
	Delete    Key = "\x1b[3~"
	Up        Key = "\x1b[A"
	Down      Key = "\x1b[B"
	Right     Key = "\x1b[C"
	Left      Key = "\x1b[D"
	Home      Key = "\x1b[H"
	End       Key = "\x1b[F"
	PageUp    Key = "\x1b[5~"
	PageDown  Key = "\x1b[6~"
	Insert    Key = "\x1b[2~"

	F1  Key = "\x1bOP"
	F2  Key = "\x1bOQ"
	F3  Key = "\x1bOR"
	F4  Key = "\x1bOS"
	F5  Key = "\x1b[15~"
	F6  Key = "\x1b[17~"
	F7  Key = "\x1b[18~"
	F8  Key = "\x1b[19~"
	F9  Key = "\x1b[20~"
	F10 Key = "\x1b[21~"
	F11 Key = "\x1b[23~"
	F12 Key = "\x1b[24~"
)

Named keys. Values are the byte sequences a terminal sends for each key.

func Alt ¶

func Alt(k any) Key

Alt returns k with Alt held. It accepts the same items as SendKeys.

A named key with a CSI or SS3 form (the cursor keys, Home, End, Insert, Delete, PageUp, PageDown and F1 to F12) gets the xterm modifier form, the way xterm sends it: Alt(Up) is CSI 1;3 A, not ESC followed by CSI A. Any other item is prefixed with ESC, the conventional meta encoding, so Alt('x') is ESC x.

An item of an unsupported type yields a bare Esc, since Alt has no way to report an error. Pass a string, rune, Key, or slice of those and that cannot happen.

func Ctrl ¶

func Ctrl(r rune) Key

Ctrl returns the byte a terminal sends for a rune typed with Control held, so Ctrl('b') is 0x02. Letters are case-insensitive.

It follows the xterm table rather than masking every rune to five bits, which is what makes the non-letter chords come out right: Ctrl('@'), Ctrl(' ') and Ctrl('2') are NUL, Ctrl('[') and Ctrl('3') are ESC, Ctrl('\\'), Ctrl(']'), Ctrl('^') and Ctrl('_') are 0x1c to 0x1f as are Ctrl('4') to Ctrl('7'), Ctrl('~') is 0x1e like Ctrl('^'), Ctrl('/') is 0x1f like Ctrl('_'), and Ctrl('?') and Ctrl('8') are DEL. A rune with no control encoding, such as a digit other than 2 to 8 or anything outside ASCII, is sent unchanged, since that is what a terminal without the kitty keyboard protocol sends for it.

Example ¶

Ctrl and Alt build chords as the bytes a terminal sends for them.

package main

import (
	"fmt"

	"github.com/Gaurav-Gosain/tuitest"
)

func main() {
	fmt.Printf("%q %q %q\n", tuitest.Ctrl('c'), tuitest.Alt('x'), tuitest.Alt(tuitest.Enter))
}
Output:
"\x03" "\x1bx" "\x1b\r"

func Mod ¶ added in v0.3.0

func Mod(k Key, mods KeyMods) Key

Mod returns a named key with modifiers held, in the xterm modifier form: the key's CSI sequence with the parameter 1 plus the modifier bits. Mod(Up, ModCtrl) is CSI 1;5 A, Mod(Delete, ModShift) is CSI 3;2 ~, and Mod(F1, ModCtrl|ModShift) is CSI 1;6 P. Modifiers add up, so Mod(Mod(Up, ModCtrl), ModShift) is Mod(Up, ModCtrl|ModShift). A modified key is sent in this form whatever the cursor key mode, as xterm does.

It applies to the named keys with a CSI or SS3 form: the cursor keys, Home, End, Insert, Delete, PageUp, PageDown and F1 to F12. Any other key is returned as it is, since it has no xterm modifier form. Use Ctrl for a control character and Alt for the ESC prefix.

type KeyMods ¶

type KeyMods int

KeyMods is a bitmask of held modifier keys.

const (
	// ModShift is the shift key.
	ModShift KeyMods = 1 << iota
	// ModAlt is the alt or meta key.
	ModAlt
	// ModCtrl is the control key.
	ModCtrl
)

type MouseAction ¶

type MouseAction int

MouseAction is what the button did.

const (
	// MousePress is a button going down.
	MousePress MouseAction = iota
	// MouseRelease is a button coming up.
	MouseRelease
	// MouseMove is motion with no button held.
	MouseMove
	// MouseDrag is motion with a button held. On the wire it is the same
	// motion bit as MouseMove; the two are distinguished by whether a button
	// is reported, and separating them is what lets a tape read as a drag.
	MouseDrag
)

type MouseButton ¶

type MouseButton int

MouseButton identifies a mouse button or wheel direction.

const (
	// MouseLeft is the primary button.
	MouseLeft MouseButton = iota
	// MouseMiddle is the middle button or wheel click.
	MouseMiddle
	// MouseRight is the secondary button.
	MouseRight
	// MouseWheelUp is one wheel notch away from the user.
	MouseWheelUp
	// MouseWheelDown is one wheel notch toward the user.
	MouseWheelDown
	// MouseWheelLeft is one horizontal wheel notch to the left.
	MouseWheelLeft
	// MouseWheelRight is one horizontal wheel notch to the right.
	MouseWheelRight
	// MouseBackward is the fourth button, "back" on most mice.
	MouseBackward
	// MouseForward is the fifth button, "forward" on most mice.
	MouseForward
	// MouseNone is no button: the button field of a motion report with nothing
	// held, and of a legacy release report, which does not say which button
	// came up.
	MouseNone
)

type MouseEncoding ¶

type MouseEncoding int

MouseEncoding is the wire format a mouse report used.

It is part of the event because replaying a recorded session has to send the program the same bytes it originally received: a program that enabled only mode 1000 does not understand an SGR report, so re-encoding a captured X10 report as SGR would silently change what the test exercises.

const (
	// MouseSGR is the modern SGR encoding (mode 1006), and the default for
	// events constructed by hand. It is the only encoding with no coordinate
	// limit and the only one that reports which button was released.
	MouseSGR MouseEncoding = iota
	// MouseX10 is the original encoding (modes 9, 1000, 1002 and 1003), which
	// packs each field into one byte offset by 32.
	MouseX10
	// MouseURXVT is the urxvt encoding (mode 1015): X10's packing written as
	// decimal parameters, so it has no coordinate limit but still cannot say
	// which button was released.
	MouseURXVT
)

type MouseEvent ¶

type MouseEvent struct {
	// Col and Row are zero-based cell coordinates; the wire format's 1-based
	// coordinates are produced during encoding. When Pixel is set they are
	// zero-based pixel offsets instead.
	Col, Row int
	// Button is the button or wheel direction involved. It is ignored for
	// MouseMove, which is motion with nothing held: to send motion with a
	// button down, use MouseDrag.
	Button MouseButton
	// Action is what the button did.
	Action MouseAction
	// Mods are the modifier keys held at the time.
	Mods KeyMods
	// Pixel reports coordinates in pixels rather than cells (mode 1016). The
	// wire format is identical to SGR's, so this can only ever be known from
	// whether the program asked for pixel reporting.
	Pixel bool
	// Enc is the wire encoding to use. The zero value is MouseSGR.
	Enc MouseEncoding
}

MouseEvent is a single mouse event at a zero-based cell coordinate.

func (MouseEvent) Encode ¶

func (e MouseEvent) Encode() (string, bool)

Encode renders the event in whichever wire encoding Enc names.

func (MouseEvent) EncodeSGR ¶

func (e MouseEvent) EncodeSGR() (string, bool)

EncodeSGR renders the event as an SGR (1006) or SGR-pixel (1016) sequence. Coordinates in the wire format are 1-based. It reports false for an event the encoding cannot express.

func (MouseEvent) EncodeURXVT ¶

func (e MouseEvent) EncodeURXVT() (string, bool)

EncodeURXVT renders the event in the urxvt encoding (mode 1015): X10's control byte and 1-based coordinates written as decimal parameters, which lifts X10's coordinate limit but keeps its inability to name a released button.

func (MouseEvent) EncodeX10 ¶

func (e MouseEvent) EncodeX10() (string, bool)

EncodeX10 renders the event in the original encoding, where the control byte and both coordinates are single bytes offset by 32.

It reports false for anything that packing cannot hold: a coordinate past column 223, which has no representation at all, and a release, which the encoding reports as the button-3 code without saying which button came up. Falling back rather than approximating is what keeps a recorded session's bytes intact.

type Option ¶

type Option func(*config)

Option configures a spawn.

func WithCastDir ¶ added in v0.3.0

func WithCastDir(dir string) Option

WithCastDir records everything the terminal shows and is sent, as an asciicast v2 recording that asciinema and other players can scrub. Every wait and every input call adds a mark, so a player can jump to each step of the test.

Under StartT and StartProgramT a terminal whose test fails is written to a new file in dir, and the test log names the file. A test that passes writes nothing. Setting TUITEST_CAST_DIR does the same for every terminal those functions start. WriteCast writes the recording at any time.

Recording keeps the output in memory, up to 16 MiB for each terminal, so it is off unless one of the two asks for it.

func WithCellSize ¶ added in v0.3.2

func WithCellSize(width, height int) Option

WithCellSize sets the size of one cell in pixels. The terminal reports it the way a real terminal does: in the PTY's window size, in the answers to CSI 14 t and CSI 16 t, and in the mode 2048 report. Without it the cell is the emulator's fallback, 10 by 20 pixels. Both must be positive; anything else keeps the fallback.

func WithDir ¶

func WithDir(path string) Option

WithDir sets the child's working directory.

func WithEnv ¶

func WithEnv(kv ...string) Option

WithEnv adds or overrides environment entries ("KEY=VALUE").

func WithFullTestLog ¶

func WithFullTestLog() Option

WithFullTestLog makes StartT copy every chunk of PTY I/O to t.Log as it arrives. Without it StartT keeps only the last StartTLogTail bytes and logs them when the test fails. A program that writes a lot then fills the log with escape sequences, so use it only to debug one test.

func WithInheritEnv ¶

func WithInheritEnv() Option

WithInheritEnv starts from the parent process environment instead of the minimal hermetic default.

func WithKillGrace ¶

func WithKillGrace(d time.Duration) Option

WithKillGrace sets how long Close waits for the program to exit after SIGTERM before it sends SIGKILL. The default is two seconds. Zero or less sends SIGTERM and then SIGKILL with no wait. A short grace makes Close fast for a program that ignores SIGTERM.

func WithLog ¶

func WithLog(w io.Writer) Option

WithLog mirrors all PTY I/O to w for debugging failing tests.

func WithOutputMirror ¶

func WithOutputMirror(w io.Writer) Option

WithOutputMirror copies the child's output to w as it arrives. Unlike WithLog, which mirrors both directions for debugging, this carries only what the program wrote, so w can be a real terminal the program is rendered onto while the harness still drives it headlessly. Used by tuitest record and tuitest replay.

func WithSemanticMarkers ¶

func WithSemanticMarkers() Option

WithSemanticMarkers enables OSC 133 tracking so the WaitForPrompt / WaitForCommand / LastCommandExit primitives work.

func WithSixel ¶ added in v0.3.2

func WithSixel() Option

WithSixel makes the terminal say it draws sixel images: its answer to the primary device attributes query (DA1) carries attribute 4, as a sixel terminal's does. The terminal does not draw the images; the program can tell what it sent from the screen and the log.

func WithSize ¶

func WithSize(cols, rows int) Option

WithSize sets the initial PTY size in cells. Both must be between 1 and 65535, the range the kernel can store; Start refuses anything else.

func WithStabilizeInterval ¶

func WithStabilizeInterval(d time.Duration) Option

WithStabilizeInterval sets the quiet window used by WaitStable.

func WithTerm ¶

func WithTerm(term string) Option

WithTerm overrides the TERM value (default "xterm-256color").

func WithTrueColor ¶

func WithTrueColor() Option

WithTrueColor sets COLORTERM=truecolor for programs that gate 24-bit color.

func WithWriteTimeout ¶

func WithWriteTimeout(d time.Duration) Option

WithWriteTimeout sets how long input (SendKeys, Type, Paste, SendMouse) waits for the program to read it. The default is DefaultWriteTimeout. Zero or less removes the limit.

A write that times out returns a *TimeoutError with the screen. Part of the input can already be in the program's input buffer, possibly half an escape sequence, so after a timeout the terminal refuses all further input. Raise the limit for a large paste into a program that reads slowly.

The write that timed out stays blocked, and keeps the PTY open, until the test binary exits. Close still returns.

type Program ¶ added in v0.3.0

type Program interface {
	// Run runs the program until it ends and returns its exit code. It reads
	// its input from in and writes its output to out, and starts at a
	// terminal of cols by rows cells. in reports io.EOF once the Terminal
	// is closed. A panic in Run ends the program with exit code 2 and the
	// panic on the screen, as it would for a Go program on a PTY.
	Run(in io.Reader, out io.Writer, cols, rows int) int
	// Resize tells the program that its terminal is now cols by rows. It is
	// called from the test's goroutine while Run runs.
	Resize(cols, rows int)
	// Stop asks the program to end. Run must return soon after. Close calls
	// it, and it may be called after Run has returned.
	Stop()
}

Program is a terminal program that runs inside the test process instead of as a child on a PTY. StartProgram puts it behind a Terminal, and the Terminal treats its output and input exactly as it treats a PTY child's: the same emulator reads the output, and the same waits, screen reads and key encoding apply. A test written against a Terminal runs against either.

There is no line discipline in between. The program reads the bytes a terminal sends, as a program in raw mode does, and what it writes reaches the screen as it is, so it writes "\r\n" to start a new line.

type Scope ¶

type Scope int

Scope selects what part of the screen a match runs against.

const (
	// ScopeScreen matches against the whole rendered screen.
	ScopeScreen Scope = iota
	// ScopeLastLine matches against the last non-blank line only.
	ScopeLastLine
)

type Screen ¶

type Screen interface {
	// Size returns the grid size in cells.
	Size() (cols, rows int)
	// Cell returns the cell at the given zero-based column and row. Out-of-bounds
	// coordinates return the zero Cell.
	Cell(col, row int) Cell
	// Cursor returns the cursor position (zero-based) and whether it is visible.
	Cursor() (col, row int, visible bool)
	// Text returns the plain-text screen, one row per line, with each line's
	// trailing blanks trimmed and trailing blank lines dropped.
	Text() string
	// Line returns the plain text of a single physical row with trailing blanks
	// trimmed, or "" for an out-of-range row. It does not de-wrap: a logical
	// line that soft-wrapped at the right margin occupies several rows and will
	// not match as one string. Match per row, or use Text and account for the
	// wrap, or widen the terminal with WithSize so the line fits.
	Line(row int) string
	// ExitCode reports the child's exit code and whether it has exited.
	ExitCode() (code int, exited bool)
}

Screen is a read-only view of the terminal grid handed to wait conditions and returned by snapshots. Every Screen value is an immutable copy taken under the terminal's lock, so a condition callback may stash it without observing a torn write from the output pump.

type TermState ¶

type TermState struct {
	// AltScreen is set while any of the alternate screen modes (47, 1047,
	// 1049) is.
	AltScreen bool
	// MouseTracking is set while any mouse reporting mode (9, 1000, 1001,
	// 1002, 1003) is.
	MouseTracking bool
	// BracketedPaste is mode 2004.
	BracketedPaste bool
	// FocusReporting is mode 1004.
	FocusReporting bool
	// CursorHidden is mode 25 reset.
	CursorHidden bool
	// contains filtered or unexported fields
}

TermState is a snapshot of the terminal modes a program has left set, plus cursor visibility. It answers "did this TUI restore the terminal?", which is a common and user-visible bug class: a program that exits without leaving the alternate screen, or with mouse reporting still on, leaves the user's shell unusable.

func (TermState) Describe ¶

func (s TermState) Describe() string

Describe lists the offending modes in a stable order, for error messages.

func (TermState) Dirty ¶

func (s TermState) Dirty() bool

Dirty reports whether any mode is left in a state that would visibly damage the user's shell after the program exits.

func (TermState) Mode ¶

func (s TermState) Mode(n int) bool

Mode reports whether the given DEC private mode number is currently set. A mode the emulator does not implement, such as 12 (cursor blink), is never recorded and always reads false.

type Terminal ¶

type Terminal struct {
	// contains filtered or unexported fields
}

Terminal is the harness handle for one spawned program.

func Start ¶

func Start(argv []string, opts ...Option) (*Terminal, error)

Start spawns argv[0] with argv[1:] in a PTY and begins pumping output.

func StartProgram ¶ added in v0.3.0

func StartProgram(prog Program, opts ...Option) (*Terminal, error)

StartProgram runs prog in the test process behind a Terminal.

The options that shape a child process do not apply: WithEnv, WithInheritEnv, WithDir, WithTerm and WithTrueColor are ignored, since the program has no environment or directory of its own. WithKillGrace bounds how long Close waits for Run to return after Stop.

func StartProgramT ¶ added in v0.3.0

func StartProgramT(tb testing.TB, prog Program, opts ...Option) *Terminal

StartProgramT is StartProgram for a test: it registers Close with t.Cleanup, fails the test if the program cannot start, and keeps the same debug log as StartT.

func StartT ¶

func StartT(tb testing.TB, argv []string, opts ...Option) *Terminal

StartT is the testing.TB-friendly constructor: it registers Close via t.Cleanup, fails the test on spawn error, and keeps a debug log for t.Log.

The log holds the last StartTLogTail bytes of PTY I/O in both directions, and goes to t.Log only when the test fails. WithFullTestLog copies every chunk to t.Log instead, and WithLog sends the log to a writer of your choice.

The test also fails when the terminal emulator panicked during the test, even if the test made no call that returned the error. A test that makes the emulator panic on purpose uses Start.

Example ¶

StartT is Start for use inside a test: it fails the test if the spawn fails, mirrors PTY traffic into t.Log, and closes the terminal in t.Cleanup.

package main

import (
	"testing"
	"time"

	"github.com/Gaurav-Gosain/tuitest"
)

// greeter is a tiny interactive program: it asks for a name and answers.
var greeter = []string{"sh", "-c", `printf 'name? '; read name; printf 'hello, %s\n' "$name"`}

func main() {
	test := func(t *testing.T) {
		term := tuitest.StartT(t, greeter, tuitest.WithSize(40, 5))
		if err := term.WaitForText("name?", 5*time.Second); err != nil {
			t.Fatal(err)
		}
		_ = term.SendKeys("gopher", tuitest.Enter)
		if err := term.WaitForText("hello, gopher", 5*time.Second); err != nil {
			t.Fatal(err)
		}
		// Compare against testdata/greeting.golden; UPDATE_GOLDEN=1 writes it.
		term.AssertGolden(t, "greeting")
	}
	_ = test
}

func (*Terminal) AssertGolden ¶

func (t *Terminal) AssertGolden(tb testing.TB, name string)

AssertGolden compares the plain-text snapshot against testdata/<name>.golden, failing the test on mismatch with a unified diff. When UPDATE_GOLDEN is set in the environment or -update is passed, it rewrites the golden instead.

It reads the screen once, as it is at the moment of the call, so wait for the state first; WaitForStable is the wait that makes sure the frame has finished drawing. Trailing newlines and CRLF line endings in the golden file are ignored, so a golden saved by an editor or checked out on Windows still matches.

func (*Terminal) AssertGoldenStyled ¶

func (t *Terminal) AssertGoldenStyled(tb testing.TB, name string)

AssertGoldenStyled is AssertGolden for the styled encoding.

func (*Terminal) Close ¶

func (t *Terminal) Close() error

Close tears down the child process group and PTY. It is idempotent.

func (*Terminal) Done ¶

func (t *Terminal) Done() <-chan struct{}

Done returns a channel closed once the child has exited and been reaped. It lets a caller select on program exit alongside its own events, which Wait cannot express because it blocks.

func (*Terminal) ExitCode ¶

func (t *Terminal) ExitCode() (int, bool)

ExitCode reports the child's exit code and whether it has exited.

The code is -1 for a child killed by a signal, not the shell's 128+signal convention, so that it can never be confused with a program that exited with that number itself. It is -1 before the child has exited too, and the second return value is the only thing that separates those two cases. Use ExitStatus to tell a crash apart from an ordinary non-zero exit.

func (*Terminal) ExitStatus ¶

func (t *Terminal) ExitStatus() (ExitStatus, bool)

ExitStatus reports how the child finished and whether it has exited at all.

Example ¶

ExitStatus separates a signal death from an ordinary non-zero exit, which ExitCode flattens to -1.

package main

import (
	"fmt"
	"time"

	"github.com/Gaurav-Gosain/tuitest"
)

func main() {
	term, err := tuitest.Start([]string{"sh", "-c", "kill -SEGV $$"}, tuitest.WithSize(40, 3))
	if err != nil {
		fmt.Println(err)
		return
	}
	defer term.Close() //nolint:errcheck

	_, _ = term.WaitExit(5 * time.Second)
	st, _ := term.ExitStatus()
	fmt.Println(st.Signaled, st.Crashed(), st)
}
Output:
true true killed by SIGSEGV

func (*Terminal) InputBytes ¶

func (t *Terminal) InputBytes() int64

InputBytes reports how many bytes have been written to the child's input so far: everything sent with SendKeys, Type, Paste and SendMouse, and the answers the terminal gave to the program's own queries, which the program reads from the same stream.

It is the input side of Progress, and it exists for the one question no quiet window can answer: whether the program has caught up with its input. A program that reports how many bytes it has read can be compared against this count, and once the two agree the program has seen everything, however long the machine took to schedule it. WaitStable can only guess, and a program starved of CPU for longer than the stabilize interval defeats the guess.

It does not take the terminal's lock, so it is safe to call from inside a WaitFor condition.

func (*Terminal) LastCommandExit ¶

func (t *Terminal) LastCommandExit() (int, bool)

LastCommandExit returns the exit code of the last finished command (OSC 133 D) and whether one has been seen. It reports false both when no command has finished and when the terminal was started without WithSemanticMarkers, so enable that option before relying on it; the WaitForPrompt and WaitForCommand waits return ErrSemanticMarkers in that case and are the better signal.

After an emulator panic it returns the value at the panic. See EmulatorPanicError.

func (*Terminal) Paste ¶

func (t *Terminal) Paste(s string) error

Paste sends text wrapped in bracketed-paste markers, the way a terminal delivers a real paste to a program that enabled mode 2004. Such programs take a different code path for pasted text than for typed text, and that path is often the less tested one.

The markers are sent whether or not the program enabled the mode, so a test can check how a program copes with markers it did not ask for. A real terminal sends a paste to such a program as plain text; to reproduce that, use Type.

Example ¶

Paste wraps text in bracketed-paste markers, the way a terminal delivers a real paste. cat -v makes the markers visible.

package main

import (
	"fmt"
	"time"

	"github.com/Gaurav-Gosain/tuitest"
)

func main() {
	term, err := tuitest.Start([]string{"sh", "-c", `echo ready; IFS= read -r line; printf '%s\n' "$line" | cat -v; sleep 5`}, tuitest.WithSize(40, 3))
	if err != nil {
		fmt.Println(err)
		return
	}
	defer term.Close() //nolint:errcheck

	_ = term.WaitForText("ready", 5*time.Second)
	_ = term.Paste("hi")
	_ = term.SendKeys(tuitest.Enter)
	_ = term.WaitForText("201~", 5*time.Second)
	fmt.Println(term.Screen().Line(1))
}
Output:
^[[200~hi^[[201~

func (*Terminal) Pid ¶

func (t *Terminal) Pid() int

Pid returns the child's process id, or 0 if it is not running.

func (*Terminal) Progress ¶

func (t *Terminal) Progress() (bytes int64, last time.Time)

Progress reports how many bytes the child has written so far and when the most recent write landed. A caller that sends input and then sees neither counter move has evidence the program stopped responding.

func (*Terminal) Resize ¶

func (t *Terminal) Resize(cols, rows int) error

Resize changes the PTY window size and the emulator grid; the child receives SIGWINCH. Like sending keys, a resize counts as input for WaitStable, since the redraw it provokes has not arrived yet.

A program that enabled in-band resize notifications (mode 2048) is sent the report as part of the call, after the PTY has its new size, the way a real terminal sends it.

Example ¶

Resize changes the PTY size, so the program receives SIGWINCH and sees the new size, and resizes the emulator grid to match.

package main

import (
	"fmt"
	"time"

	"github.com/Gaurav-Gosain/tuitest"
)

func main() {
	term, err := tuitest.Start([]string{"sh", "-c", "stty size; read x; stty size; sleep 5"}, tuitest.WithSize(80, 24))
	if err != nil {
		fmt.Println(err)
		return
	}
	defer term.Close() //nolint:errcheck

	_ = term.WaitForText("24 80", 5*time.Second)
	_ = term.Resize(50, 10)
	_ = term.SendKeys(tuitest.Enter)
	_ = term.WaitForText("10 50", 5*time.Second)

	cols, rows := term.Screen().Size()
	fmt.Println(cols, rows)
	fmt.Println(term.Snapshot())
}
Output:
50 10
24 80
10 50

func (*Terminal) Screen ¶

func (t *Terminal) Screen() Screen

Screen returns an immutable view of the current screen.

While the program is inside a synchronized update (DEC mode 2026) this is the last complete frame, not the half-drawn one being built, which is what a real terminal shows too. The waits read the screen the same way.

func (*Terminal) SendKeys ¶

func (t *Terminal) SendKeys(items ...any) error

SendKeys types a sequence of named keys, chords, runes, and strings. Plain strings and runes are sent literally; Key values carry their own escape sequences. Items may be string, rune, Key, []string, []Key, or []any of those; anything else is rejected with an error rather than sent. Example:

term.SendKeys("git status", tuitest.Enter)
term.SendKeys(tuitest.Ctrl('b'), "%")

A Key is sent the way a terminal sends that key under the keyboard modes the program has set, the way a user's terminal would:

  • With no mode set, a Key is sent as its constant says.
  • Once the program has set DECCKM (mode 1), the unmodified arrow keys, Home and End are sent as SS3 sequences (ESC O A), which full-screen programs built on terminfo set at startup and then match against.
  • Once the program has pushed kitty keyboard flags (CSI > flags u), keys follow the kitty protocol for those flags: Ctrl('b') is CSI 98;5 u, Esc is CSI 27 u, and with the flag that reports every key Enter is CSI 13 u.
  • At modifyOtherKeys level 2 (CSI > 4;2 m), a key with Ctrl or Alt is sent as CSI 27;mod;code ~.

Strings and runes are text and are sent as they are, whatever the modes: use Key values for keystrokes. Only key presses are sent, never key releases.

func (*Terminal) SendMouse ¶

func (t *Terminal) SendMouse(ev MouseEvent) error

SendMouse encodes a mouse event and sends it to the child, using the wire encoding named by the event's Enc field. The program under test must have enabled the matching mouse reporting mode for it to react.

func (*Terminal) Snapshot ¶

func (t *Terminal) Snapshot() string

Snapshot returns the current plain-text screen.

func (*Terminal) SnapshotStyled ¶

func (t *Terminal) SnapshotStyled() string

SnapshotStyled returns the styled, diff-friendly encoding of the screen: each row's plain text followed by indented attribute runs for spans that differ from the default style. A screen with no styling degrades to the plain form.

func (*Terminal) TermState ¶

func (t *Terminal) TermState() TermState

TermState returns the current mode state of the emulated terminal. Call it after the child has exited to check that it restored the terminal.

After an emulator panic it returns the state at the panic. See EmulatorPanicError.

Example ¶

TermState reports the modes a program left set. A program that exits on the alternate screen leaves the user's shell unusable, and Dirty catches it.

package main

import (
	"fmt"
	"time"

	"github.com/Gaurav-Gosain/tuitest"
)

func main() {
	term, err := tuitest.Start([]string{"sh", "-c", `printf '\033[?1049h\033[?25l'`}, tuitest.WithSize(40, 3))
	if err != nil {
		fmt.Println(err)
		return
	}
	defer term.Close() //nolint:errcheck

	_, _ = term.WaitExit(5 * time.Second)
	st := term.TermState()
	fmt.Println(st.Dirty(), st.AltScreen, st.CursorHidden)
}
Output:
true true true

func (*Terminal) Type ¶

func (t *Terminal) Type(s string) error

Type sends literal text with no key-name interpretation (tmux send-keys -l).

func (*Terminal) Wait deprecated

func (t *Terminal) Wait(timeout time.Duration) (int, error)

Wait is the former name of WaitExit, kept so existing tests keep compiling.

Deprecated: use WaitExit. "Wait" read as a sibling of the WaitFor family, which wait on screen state, when in fact it waits for process exit.

func (*Terminal) WaitExit ¶

func (t *Terminal) WaitExit(timeout time.Duration) (int, error)

WaitExit blocks until the child exits or timeout elapses, returning the exit code. On timeout it returns -1 and a *TimeoutError, which unwraps to ErrTimeout like every other wait. A child killed by a signal also returns -1, with a nil error; ExitStatus is what tells the two apart.

func (*Terminal) WaitFor ¶

func (t *Terminal) WaitFor(cond func(Screen) bool, timeout time.Duration) error

WaitFor blocks until cond returns true on the current screen, or timeout.

cond is called with the terminal's lock held, once at the start and then each time the screen can have changed: the program wrote output, the terminal was resized, input reached the program, or the program exited. It is not called on a timer in between, so a condition that reads the clock instead of the screen does not work. cond must be quick and must not call back into the Terminal. The Screen it receives is immutable and may be kept.

Like every wait, WaitFor treats a timeout of zero or less as one second, and returns an error wrapping ErrChildExited if the program exits before the condition holds, or ErrTimeout if time runs out. The error message carries the screen at that moment.

The error describes the condition as "custom condition". Use WaitForDesc to say what the condition waits for.

Example ¶

WaitFor takes any condition on the screen. Here it waits for a cell to be drawn bold, which no text match can see.

package main

import (
	"fmt"
	"time"

	"github.com/Gaurav-Gosain/tuitest"
)

func main() {
	term, err := tuitest.Start([]string{"sh", "-c", `printf 'plain \033[1mBOLD\033[0m'; sleep 5`}, tuitest.WithSize(40, 3))
	if err != nil {
		fmt.Println(err)
		return
	}
	defer term.Close() //nolint:errcheck

	err = term.WaitFor(func(s tuitest.Screen) bool {
		return s.Cell(6, 0).Bold
	}, 5*time.Second)
	fmt.Println(err, term.Screen().Cell(6, 0).Content, term.Screen().Cell(0, 0).Bold)
}
Output:
<nil> B false

func (*Terminal) WaitForCommand ¶

func (t *Terminal) WaitForCommand(timeout time.Duration) error

WaitForCommand blocks until the current command finishes (OSC 133 D). Requires WithSemanticMarkers.

Example ¶

WaitForPrompt and WaitForCommand follow a shell through OSC 133 semantic markers, which the shell (or its prompt framework) has to emit.

Both wait for a marker newer than the call, so a marker that arrives before the wait starts is not seen. The script sleeps before each one to keep this example deterministic; a real shell is slower than the Go side anyway.

package main

import (
	"fmt"
	"time"

	"github.com/Gaurav-Gosain/tuitest"
)

func main() {
	// A stand-in for a shell with shell integration: prompt, command, exit 7.
	script := `sleep 0.2; printf '\033]133;A\007$ \033]133;B\007'; read x; sleep 0.2; printf '\033]133;C\007ran\n\033]133;D;7\007'; sleep 5`
	term, err := tuitest.Start([]string{"sh", "-c", script}, tuitest.WithSize(40, 5), tuitest.WithSemanticMarkers())
	if err != nil {
		fmt.Println(err)
		return
	}
	defer term.Close() //nolint:errcheck

	if err := term.WaitForPrompt(5 * time.Second); err != nil {
		fmt.Println(err)
		return
	}
	_ = term.SendKeys(tuitest.Enter)
	if err := term.WaitForCommand(5 * time.Second); err != nil {
		fmt.Println(err)
		return
	}
	fmt.Println(term.LastCommandExit())
}
Output:
7 true

func (*Terminal) WaitForDesc ¶

func (t *Terminal) WaitForDesc(desc string, cond func(Screen) bool, timeout time.Duration) error

WaitForDesc is WaitFor with a description of the condition. The description is the Want field of the error, and the error message says "waiting for" desc, so write it to complete that phrase:

term.WaitForDesc("the status bar to show 3 windows", func(s tuitest.Screen) bool {
	return strings.Contains(s.Line(23), "3 windows")
}, time.Second)

func (*Terminal) WaitForMatch ¶

func (t *Terminal) WaitForMatch(re *regexp.Regexp, scope Scope, timeout time.Duration) error

WaitForMatch blocks until re matches within the given scope.

Example ¶

WaitForMatch takes a regexp, and ScopeLastLine restricts it to the last non-blank row, which is where a prompt or a status line usually is.

package main

import (
	"fmt"
	"regexp"
	"time"

	"github.com/Gaurav-Gosain/tuitest"
)

func main() {
	term, err := tuitest.Start([]string{"sh", "-c", "echo 'build 1 of 3'; echo 'done in 42ms'; sleep 5"}, tuitest.WithSize(40, 5))
	if err != nil {
		fmt.Println(err)
		return
	}
	defer term.Close() //nolint:errcheck

	re := regexp.MustCompile(`done in \d+ms`)
	if err := term.WaitForMatch(re, tuitest.ScopeLastLine, 5*time.Second); err != nil {
		fmt.Println(err)
		return
	}
	fmt.Println(re.FindString(term.Screen().Text()))
}
Output:
done in 42ms

func (*Terminal) WaitForOutput ¶

func (t *Terminal) WaitForOutput(timeout time.Duration) error

WaitForOutput blocks until the child writes anything at all after the call begins, or it exits, or timeout elapses.

This is the primitive for "wait until the program reacts to what I just sent", which WaitStable does not express: WaitStable asks whether output has been quiet for a window, and after a pause that is already true, so it returns immediately without the program having done anything. Use WaitStable to wait for a burst of output to finish, and WaitForOutput to wait for a reaction to begin. A child that has exited counts as settled, since no further output can arrive.

func (*Terminal) WaitForPrompt ¶

func (t *Terminal) WaitForPrompt(timeout time.Duration) error

WaitForPrompt blocks until a new shell prompt (OSC 133 A) is drawn. Requires WithSemanticMarkers.

func (*Terminal) WaitForStable ¶

func (t *Terminal) WaitForStable(cond func(Screen) bool, timeout time.Duration) error

WaitForStable blocks until cond holds on a screen whose content has not changed for the stabilize interval (see WithStabilizeInterval), or until timeout.

It is for the case WaitFor handles badly: the text a test waits for is drawn before the rest of the frame it belongs to. A program redraws from the top down and the PTY delivers the frame in pieces, so the moment a marker near the top appears, the rows below it can still hold the previous frame, and an assertion on them made straight after WaitFor fails against a screen that is correct a moment later. WaitForStable waits for the frame to finish as well. It is also the way to read a value off the screen that is still moving, such as a counter or a scroll position: wait for it to stop, then read it.

Only the content of the cells counts as a change: text, colours and attributes, and the size. Output that repaints the same content, and cursor movement, do not restart the window. As with WaitStable, the window is not considered to start before the last input tuitest sent, so a screen that already satisfied cond before a keystroke is not reported until the program has had the interval to react to it. A child that has exited cannot change the screen again, so once it has, cond holding is enough.

Programs that draw inside synchronized updates (mode 2026) are already never seen half drawn, since the harness shows the previous frame until the update closes, the way a real terminal does. WaitForStable still helps with the ones that do not, and with a program that draws one logical frame in several updates.

func (*Terminal) WaitForText ¶

func (t *Terminal) WaitForText(substr string, timeout time.Duration) error

WaitForText blocks until the plain-text screen contains substr.

Example ¶

A wait that runs out of time says what it waited for and carries the screen, and errors.Is tells a timeout apart from the program exiting early.

package main

import (
	"errors"
	"fmt"
	"time"

	"github.com/Gaurav-Gosain/tuitest"
)

func main() {
	term, err := tuitest.Start([]string{"sh", "-c", "echo starting; sleep 5"}, tuitest.WithSize(40, 3))
	if err != nil {
		fmt.Println(err)
		return
	}
	defer term.Close() //nolint:errcheck

	if err := term.WaitForText("starting", 5*time.Second); err != nil {
		fmt.Println(err)
		return
	}
	err = term.WaitForText("ready", 200*time.Millisecond)
	fmt.Println(errors.Is(err, tuitest.ErrTimeout))

	var te *tuitest.TimeoutError
	if errors.As(err, &te) {
		fmt.Println(te.Screen)
	}
}
Output:
true
starting

func (*Terminal) WaitStable ¶

func (t *Terminal) WaitStable(timeout time.Duration) error

WaitStable blocks until the terminal has been quiet for the stabilize interval (see WithStabilizeInterval), or until timeout. A child that has exited counts as stable.

The quiet window is measured from the later of the last output byte and the last input tuitest sent. That matters: measured from output alone, calling WaitStable immediately after SendKeys would return against the pre-keystroke screen whenever the program had already been idle for the interval. Waiting out the window from the keystroke instead gives the program that long to start reacting, and any byte it produces restarts the window.

A program that has not written anything yet is never stable. Starting a process takes long enough, on a loaded machine or under -race, that a quiet window measured from spawn used to elapse before the first byte arrived, and WaitStable then returned a blank screen. A program that never writes at all makes WaitStable time out.

It is still a heuristic. A program that takes longer than the stabilize interval to react to input will be reported stable too early, and no quiescence rule can distinguish that from a program with nothing to say. Prefer WaitForText, WaitForMatch or WaitFor whenever the expected end state is known, and WaitForStable when the state is known but may still be drawing. Reach for WaitStable only after heavy output where it is not known at all.

func (*Terminal) WriteCast ¶ added in v0.3.0

func (t *Terminal) WriteCast(w io.Writer) error

WriteCast writes the terminal's recording to w as an asciicast v2 file. It returns an error when the terminal was started without WithCastDir and without TUITEST_CAST_DIR, since then nothing was recorded.

type TimeoutError ¶

type TimeoutError struct {
	// Op is the wait that failed, such as "WaitForText".
	Op string
	// Want describes the condition in words, such as `text "ready"`.
	Want string
	// Elapsed is how long the wait actually took.
	Elapsed time.Duration
	// Screen is the plain-text screen at the moment of the failure.
	Screen string
	// TailLog is the tail of the mirrored PTY I/O.
	TailLog string
}

TimeoutError is returned by every wait that times out. Its message includes a full screen dump and the tail of the mirrored I/O log, so a failing CI run shows exactly what was on screen instead of a bare "timeout". It unwraps to ErrTimeout.

func (*TimeoutError) Error ¶

func (e *TimeoutError) Error() string

func (*TimeoutError) Unwrap ¶

func (e *TimeoutError) Unwrap() error

Unwrap makes errors.Is(err, ErrTimeout) true for every wait timeout.

Directories ¶

Path Synopsis
cmd
tuitest command
Command tuitest tests terminal programs from the command line.
Command tuitest tests terminal programs from the command line.
Package fixtures provides in-process helpers for testing code that consumes terminal output: FakeShell, an io.ReadWriteCloser that stands in for the shell side of a PTY, and ANSIBuilder, which assembles escape sequences without hand-written byte strings.
Package fixtures provides in-process helpers for testing code that consumes terminal output: FakeShell, an io.ReadWriteCloser that stands in for the shell side of a PTY, and ANSIBuilder, which assembles escape sequences without hand-written byte strings.
Package fuzz drives a terminal program with randomised but structured input and watches for the ways a TUI breaks: crashing, hanging, corrupting the screen model, growing without bound, or exiting without restoring the terminal.
Package fuzz drives a terminal program with randomised but structured input and watches for the ways a TUI breaks: crashing, hanging, corrupting the screen model, growing without bound, or exiting without restoring the terminal.
vtgen
Package vtgen generates terminal input that looks like something a program would actually emit, by grammar rather than by byte, for fuzzing a VT parser.
Package vtgen generates terminal input that looks like something a program would actually emit, by grammar rather than by byte, for fuzzing a VT parser.
internal
cli
Package cli implements the tuitest command line.
Package cli implements the tuitest command line.
emu
Package emu holds the VT emulator adapter used by tuitest.
Package emu holds the VT emulator adapter used by tuitest.
ptyproc
Package ptyproc owns the process and PTY lifecycle for tuitest: spawning a child attached to a pseudo-terminal, pumping its output, resizing, EOF and exit-code handling, and process-tree teardown.
Package ptyproc owns the process and PTY lifecycle for tuitest: spawning a child attached to a pseudo-terminal, pumping its output, resizing, EOF and exit-code handling, and process-tree teardown.
textdist
Package textdist provides the string distance behind "did you mean" hints.
Package textdist provides the string distance behind "did you mean" hints.
Package tape implements the small VHS-inspired tape language for tuitest's CLI and a player that drives a tuitest.Terminal.
Package tape implements the small VHS-inspired tape language for tuitest's CLI and a player that drives a tuitest.Terminal.
Package tuiosx holds the tuios-specific conveniences for tuitest: a prefix chord helper and a spawn helper that isolates each tuios instance in its own temporary XDG state so parallel tests do not collide on a shared daemon socket.
Package tuiosx holds the tuios-specific conveniences for tuitest: a prefix chord helper and a spawn helper that isolates each tuios instance in its own temporary XDG state so parallel tests do not collide on a shared daemon socket.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL