microsoft/tui-test

💻 control, record, & test any tui app / cli with popular terminals - makes the terminal fully accessible to AI

What it solves

tui-test solves the problem of reliably automating and testing terminal applications and shell sessions across Windows, Linux, and macOS. It gives you structured access to a running terminal's state (visible text, styles, cursor position, scrollback, clipboard, etc.) and lets you perform realistic user actions like typing, clicking, scrolling, and resizing. This is especially useful for validating full-screen TUI apps, scripting repetitive terminal workflows, and giving AI agents a controlled way to interact with command-line environments.

How it works

tui-test controls real terminal sessions rather than simulating them. It spawns a shell or program inside a terminal backend (like Alacritty, Ghostty, Rio, or xterm.js) and then exposes a uniform set of operations through a CLI and native libraries for Rust, Python, JavaScript, and Go. You can issue commands to find text on the screen (with regex, anchors, style matching), perform keyboard and mouse input, read terminal state (exit codes, cursor, viewport, bell events), wait for conditions (text, idle, exit, readiness), and capture output as screenshots, GIF/MP4/APNG recordings, or asciinema casts. Sessions persist between CLI commands, and the same underlying engine works across all supported languages. For AI agents, the tool provides structured outputs (JSON, trace files) and a skill command to integrate with agent workflows.

Who it’s for

This is built for developers and QA engineers who need to automate and test terminal UIs, especially cross-platform tools and full-screen apps. It’s also suited for AI agents that require structured access to terminal state and controlled input, and for anyone writing automation scripts for shells or CLI programs.

Highlights

  • Cross-platform support: Windows, Linux, macOS with multiple shells (bash, zsh, fish, PowerShell, cmd, etc.)
  • Multiple interfaces: CLI plus native libraries for Rust, Python, JavaScript, and Go
  • Rich text locators: regex, anchors (before/after), style matching, link verification, and composable locators (AND/OR)
  • Full input simulation: keyboard, mouse click/drag/scroll, resize, signals, and raw data writing
  • State inspection: cursor, viewport, clipboard, title, bells, exit code, command output, and more
  • Wait and assert commands with configurable timeouts (text, idle, exit, readiness)
  • Capture and recording: SVG/PNG screenshots, APNG/GIF/MP4 recordings, and asciinema casts
  • Trace viewer with structured diagnostics (trace.md, trace.json, timeline.json) for failed assertions
  • AI-agent friendly: usage, agent-context, and skill commands that expose the full command schema and agent guide
  • Configurable via tui-test.toml for profiles, colors, recording style, and trace settings

Related

  • Project
  • Project
  • Project
  • Project