Tui Testing Debugging

TUI Testing and Debugging with Snapshots, PTYs, Virtual Terminals, and ConPTY

Use this skill when a TUI needs reliable tests or when an interactive terminal bug must be reproduced outside a human terminal session.

Four-layer test strategy

1. Pure state tests. Test reducers, update functions, focus transitions, validation, sorting, filtering, and command scheduling without a terminal. 2. Component/render snapshots. Render widgets at fixed width, height, theme, color level, locale, and time. Compare stable text or cell grids. 3. Virtual terminal tests. Feed ANSI output into a terminal emulator and assert final cells, cursor, styles, scrollback, and cleanup. 4. PTY integration tests. Spawn the real program, send keys/paste/resize, and assert visible behavior and exit status.

Snapshot stabilization

Freeze or normalize:

• Terminal size.
• Theme and color support.
• Time, random IDs, network data, spinners, cursor blink.
• Unicode mode and ambiguous-width assumptions.
• File paths when tests run cross-platform.
• Progress rates and async scheduling.

Prefer semantic assertions for behavior and snapshots for stable visual contracts.

Debugging workflow

1. Reproduce with the smallest terminal size and input sequence. 2. Capture raw input and output bytes when protocol behavior is suspected. 3. Separate stdout, stderr, logs, and alternate-screen output. 4. Disable animations and color to isolate layout from style. 5. Test outside and inside tmux/screen/SSH if relevant. 6. On Windows, test through ConPTY when Windows support is claimed.

CI rules

• Do not assume CI has a real TTY.
• Use PTY wrappers where integration tests require terminal behavior.
• Mark terminal-emulator-specific tests explicitly.
• Keep snapshots deterministic and reviewable.
• Capture logs and final terminal frames as artifacts on failure.

Failure modes

Reference files

• references/test-strategy.md - Test layers, tools, and assertions by ecosystem.
• references/debugging-playbook.md - Byte capture, terminal reset, CI, Windows, and flake triage.

TUI Debugging Playbook

Capture useful evidence

• Terminal emulator and version.
• OS and shell.
• TERM, COLORTERM, TERM_PROGRAM, WT_SESSION, TMUX, STY, SSH_TTY.
• Terminal size and font if Unicode alignment is involved.
• Raw input sequence and output bytes for protocol issues.
• Final visible frame and logs.
• Whether stdout/stderr were TTYs, pipes, or redirected files.

Reset corrupted terminals

Common recovery steps include leaving the app, running reset, running stty sane on Unix-like systems, reopening the tab, or using the app's documented --no-tui mode. Tests should verify cleanup so users rarely need these.

Byte-level debugging

When escape sequences are suspected, inspect raw bytes separately from rendered output. Capture hex dumps of input and output streams, annotate ESC/CSI/OSC/DCS boundaries, and compare against a virtual terminal's final cell grid. A virtual terminal assertion may show the screen is correct even when byte sequences vary. Conversely, byte captures can reveal missing cleanup sequences, unbalanced SGR, unsafe OSC output, or pasted data being parsed as commands.

Hex dump annotation example:

00000000  1b 5b 3f 31 30 34 39 68  1b 5b 3f 32 35 6c 1b 5b  |.[?1049h.[?25l.[|
          ESC [ ? 1 0 4 9 h        ESC [ ? 2 5 l  ESC [
          enter alt screen          hide cursor
00000010  33 31 6d 45 72 72 6f 72  1b 5b 30 6d              |31mError.[0m|
          SGR red "Error"           SGR reset

Annotate boundaries first, then interpret parameters. For input bugs, preserve timing and partial reads because parsers often fail when an escape sequence is split across reads.

Byte capture and replay harness shape

A minimal capture should include bytes and context:

{
  "width": 80,
  "height": 24,
  "env": {"TERM": "xterm-256color", "TMUX": ""},
  "events": [
    {"t_ms": 0, "kind": "spawn"},
    {"t_ms": 30, "kind": "stdin", "bytes_hex": "1b5b3230307e70617374651b5b3230317e"},
    {"t_ms": 60, "kind": "resize", "width": 100, "height": 30},
    {"t_ms": 90, "kind": "stdout", "bytes_hex": "1b5b3f32356c..."}
  ]
}

Replay modes:

1. Feed input events into the update loop with a fake clock to isolate state bugs. 2. Spawn the binary under a PTY and replay stdin/resize timing to reproduce integration bugs. 3. Feed captured stdout into a virtual terminal to assert final cells and terminal modes.

Keep sensitive data out of recordings. Redact tokens before saving, and render escape bytes visibly when sharing logs.

Recording and replay

For hard bugs, record terminal dimensions, environment variables, input events, paste payloads, resize events, timing, and output bytes. Build a replay harness that feeds the same event stream into state/update logic or a PTY. Keep sensitive data out of recordings and sanitize escape sequences before sharing logs.

Common failure signatures

Windows and ConPTY

Windows terminal behavior depends on host, ConPTY, virtual terminal processing, code page/UTF-8 handling, and the child process model. If a project claims Windows support, test the actual executable through Windows terminal paths, not only Unix PTY simulations.

ConPTY debugging checklist:

• Confirm output VT processing is enabled when using low-level console APIs.
• Confirm UTF-8 mode or framework Unicode conversion behavior.
• Test Ctrl-C, process termination, and child cleanup.
• Compare Windows Terminal and classic conhost if both are supported.
• Capture stdout/stderr bytes around resize and shutdown; ConPTY can coalesce or transform output differently from Unix PTYs.

TUI Test Strategy Reference

What to assert

• State tests: model transitions, commands scheduled, errors, focus, validation.
• Render snapshots: visible text, layout regions, styles when meaningful, accessibility labels if framework exposes them.
• Virtual terminal tests: final grid, cursor, attributes, scrollback, alternate screen cleanup.
• PTY tests: end-to-end key sequences, paste, resize, exit status, stdout/stderr separation.

Fixed-size snapshot contract

A useful snapshot is a contract, not a screenshot. Freeze every input that can change rendering:

snapshot: table-detail-empty
terminal:
  width: 80
  height: 24
  color: 16
  unicode: ascii
  background: dark
locale: C.UTF-8
clock: 2026-01-02T03:04:05Z
random_seed: 1234
framework: ratatui 0.x / textual x.y / bubbletea x.y
input_state:
  focus: search
  selected_row: 0
  scroll_offset: 0
redactions:
  - timestamps
  - temp paths
assertions:
  - no raw ESC bytes in visible cells
  - selected row has textual marker as well as style

Snapshot visible cells and meaningful styles separately where possible. Avoid snapshots that depend on cursor blink, spinners, live network data, localized time formats, terminal theme RGB values, or font-specific glyphs. Keep Unicode and ASCII snapshots separate when glyph choices differ.

PTY pseudo-flow

End-to-end PTY tests should drive the real binary:

spawn app with env TERM=xterm-256color, COLUMNS=80, LINES=24
wait until visible text contains "Search"
send keys: "abc", Enter
expect visible text contains "3 results"
resize pty to 100x30
expect visible text contains "100x30-specific layout" or stable detail pane
send bracketed paste: ESC[200~payload ESC[201~
expect payload appears literally, not as commands
send Ctrl-C
expect exit code 130 or documented interrupt code
assert terminal cleanup: cursor visible, alt screen left, raw mode restored
capture artifacts on failure: raw bytes, final grid, stderr, env, dimensions

Use polling with timeouts rather than fixed sleeps. Assert stdout and stderr separately; debug logs should not corrupt the screen.

Virtual terminal assertion shape

A virtual terminal test feeds bytes into an emulator model and asserts the final state:

{
  "given": {"width": 40, "height": 8},
  "feed": "raw output bytes from renderer",
  "expect": {
    "cursor": {"row": 7, "col": 0, "visible": true},
    "alt_screen": false,
    "cells": [
      {"row": 0, "col": 0, "text": "Status", "fg": "bold"},
      {"row": 2, "col": 0, "text": "No results"}
    ],
    "scrollback_contains": [],
    "forbidden_modes": ["mouse", "bracketed_paste"]
  }
}

Prefer final-cell assertions over exact byte assertions unless validating a protocol encoder. Byte-for-byte output can vary while rendering is correct; final-cell assertions catch user-visible regressions.

Ecosystem examples

• Rust Ratatui: use fixed-size buffers and snapshot rendered widgets; integration-test event loops through PTY tools.
• Python Textual: use Pilot-style app tests for interactions; combine with unit tests for reactive state.
• Python curses/prompt_toolkit: isolate state logic; use Pexpect or PTY wrappers for integration.
• Go Bubble Tea: test Update and View separately; use PTY tests for full program behavior.
• Node Ink: use component testing utilities; use node-pty for real terminal flows.
• .NET Terminal.Gui/Spectre.Console: isolate view models and render output; use terminal/console abstraction tests.

Golden file hygiene

Golden files should be small, stable, and intentional. Store metadata: width, height, color mode, Unicode/ASCII mode, locale, and framework version assumptions. Provide a clear review flow for intentional visual changes.

Golden metadata template:

name: dashboard-80x24-dark-256color
command: app dashboard --fixture fixtures/dashboard.json
width: 80
height: 24
stdin: []
env:
  TERM: xterm-256color
  NO_COLOR: null
  COLORTERM: truecolor
platforms_verified:
  - linux-pty
  - windows-conpty
updated_by: intentional visual change description
review_notes: "Column order changed; error state unchanged."

Property and fuzz testing

Property-based tests are useful for reducers, focus traversal, viewport math, Unicode truncation, wrapping, table column sizing, and parser boundaries. Fuzz terminal input parsers with partial escape sequences, malformed CSI/OSC/DCS, huge paste payloads, invalid UTF-8 where applicable, and resize storms.

CI matrix and ConPTY notes

A credible cross-platform TUI CI plan includes non-TTY tests, Unix PTY tests, Windows ConPTY tests when Windows is supported, fixed-size snapshot tests, and at least one smoke test inside a multiplexer if tmux/screen support is claimed. Store failure artifacts: raw bytes, final virtual screen, logs, dimensions, and environment variables.

Windows notes:

• Run at least one job on Windows, not only Wine or Unix PTY emulation.
• Prefer Windows Terminal/ConPTY paths for modern behavior and a classic conhost smoke test if you claim older console support.
• Verify UTF-8/code page setup, Ctrl-C behavior, resize delivery, process teardown, and virtual terminal processing.
• ConPTY is not byte-identical to Unix PTYs; avoid tests that assume Unix signal or line-discipline details.
• Keep Windows snapshots separate if line endings, fonts, or console mode behavior differ.