mcpField
T
tui-testing-debugging

tui-testing-debugging

github.com/josiahsiegelTesting & quality5964 installsUpdated 19w ago
Repository

About tui-testing-debugging

A skill for developers testing and debugging terminal UI applications. It combines state, snapshot, virtual-terminal, and PTY testing with practical guidance for reproducing terminal-specific failures.

Key features

  1. 01Four-layer TUI test strategy
  2. 02Stable render snapshots
  3. 03Virtual terminal assertions
  4. 04PTY-based integration tests
  5. 05Terminal debugging workflow
  6. 06CI and ConPTY guidance

Use cases

  1. 01Testing TUI behavior without a real terminal
  2. 02Reproducing bugs from captured terminal input
  3. 03Reducing flaky visual snapshots
  4. 04Diagnosing terminal-specific CI failures

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/josiahsiegel/claude-plugin-marketplace --skill tui-testing-debugging

After installing, type/tui-testing-debuggingin Claude Code to confirm it loaded.

Bundled filesreferences/debugging-playbook.mdreferences/test-strategy.md

Details

From the project README

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

SymptomLikely causeFix
Snapshot flaketime, spinner, random data, terminal widthfreeze inputs and normalize output
Works manually, fails in CIno TTY or different TERMcreate PTY or use non-TUI mode
Windows tests fail onlyUnix PTY assumptionstest via ConPTY and account for line endings
Raw bytes differ but screen sametesting sequences not final cellsassert virtual terminal state
Debug logs corrupt UIlogs write to controlled screenroute logs to file or panel

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.

Comments

Markdown supported