tui-test

tui-test controls, inspects, tests, and records real shell sessions and full-screen terminal apps on Windows, Linux, and macOS. Use it from the CLI or call the same engine from Rust, Python, or JavaScript. It works for AI agents that need structured access to terminal state, terminal automation, and terminal ui application testing.

Installation · Quick start · AI agents · API references · Configuration

Installation

CLI

Homebrew

brew tap microsoft/tui-test https://github.com/microsoft/tui-test
brew install tui-test

Install script

macOS and Linux:

curl --proto '=https' --tlsv1.2 -LsSf https://raw.githubusercontent.com/microsoft/tui-test/main/install/install.sh | TUI_TEST_VERSION=beta sh

Windows:

$env:TUI_TEST_VERSION = "beta"
irm https://raw.githubusercontent.com/microsoft/tui-test/main/install/install.ps1 | iex

You can also download a binary from GitHub Releases.

Libraries

Language	Install	Reference
Rust 1.90+	cargo add tui-test-rs@0.1.0-beta.5	docs.rs
Python 3.8+	pip install --pre tui-test	Python API
Node 20+	npm install @microsoft/tui-test@beta	JavaScript API

Add the Rust recording-raster feature for APNG, GIF, and MP4 output. It uses installed fonts; recording-font-jetbrains-mono* bundles a font.

Quick start

The CLI and libraries expose the same terminal actions. Python, JavaScript, and Rust sessions run in-process and do not require the CLI.

CLI

tui-test run my-app
tui-test expect text "Ready"
tui-test click text "Continue"
tui-test expect text "Done"
tui-test screenshot -o result.svg
tui-test close

Python

import asyncio
from tui_test import TuiTest

async def main():
    async with TuiTest.ephemeral() as terminal:
        await terminal.run("my-app")
        await terminal.get_by_text("Ready").expect()
        await terminal.get_by_text("Continue").click()
        await terminal.get_by_text("Done").expect()

asyncio.run(main())

Python API reference

JavaScript

import { TuiTest } from "@microsoft/tui-test";

const terminal = TuiTest.ephemeral();

try {
  await terminal.run("my-app");
  await terminal.getByText("Ready").expect();
  await terminal.getByText("Continue").click();
  await terminal.getByText("Done").expect();
} finally {
  await terminal.closeQuiet();
}

JavaScript API reference

Rust

use tui_test::{OpenOptions, Operation, Session};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let terminal = Session::new("example");
    terminal.open(OpenOptions::default())?;
    terminal.execute(Operation::Submit {
        data: Some("echo hello".into()),
    })?;
    terminal.get_by_text("hello").last().expect()?;
    terminal.close()?;
    Ok(())
}

Rust API reference

API references

Surface	Reference
CLI	CLI reference
Rust	docs.rs
Python	bindings/python/README.md
JavaScript	bindings/js/README.md

CLI reference

Global options

Option	Description
--session NAME	Select a session. Default: default or TUI_TEST_SESSION.
--json	Print JSON.
--verbose, -v	Write a session log.
--failure-artifacts DIR	Write structured assertion artifacts.
--failure-artifact-mode MODE	Select none, text, html, or all (default when exports are enabled).
--failure-artifact-recording	Copy the automatic cast through the failure boundary.
--diagnostic-context KEY=VALUE	Add safe caller context to failure details.

CLI sessions persist between commands. open and run reuse a live session unless --restart is set.

Sessions

Command	Description
open [options]	Open a shell.
run [options] PROGRAM [ARGS...]	Run a program.
[global options] -- PROGRAM [ARGS...]	Alias for run.
restart [--graceful-timeout MS]	Restart the session.
sessions	List sessions.
close [--all]	Close one or all sessions.
daemon start	Start the session daemon.
daemon status	Show daemon status.
daemon stop [--all]	Stop one or all daemons.

open and run accept --backend, --cols, --rows, --cwd, repeatable --env KEY=VALUE, --wait-ready, --no-wait-ready, --restart, --config, --profile, --timeout-<class> MS, and --screen-history-limit COUNT. open also accepts --shell.

Text locators

tui-test find text TEXT [options]
tui-test expect text TEXT [options]
tui-test click text TEXT [options]
tui-test highlight text TEXT [options]

Command	Description
find text	Return current matches and cell spans.
expect text	Retry until the locator passes.
click text	Retry, then click the middle cell.
highlight text	Mark matches in screenshots and the live monitor.

Locator options:

Option	Description
--regex	Treat TEXT as a regular expression.
--full	Include scrollback.
--whitespace exact|normalize	Choose whitespace matching.
--after-text TEXT	Search after an anchor.
--before-text TEXT	Search before an anchor.
--after-regex, --before-regex	Treat the anchor as a regular expression.
--after-match MODE, --before-match MODE	Select an anchor with any, unique, first, or last.
--after-nth N, --before-nth N	Select a zero-based anchor.
--match MODE	Select any, unique, first, or last.
--nth N	Select a zero-based match.

Style options are --fg, --bg, --bold, --dim, --italic, --underline-style, --underline-color, --inverse, --hidden, --strikethrough, and --blink. Boolean styles accept =false.

--link URI separately requires every matched cell, including spaces, to have that OSC 8 target. --link "" requires no link.

Programmatic locators add getByLink() / get_by_link(), cell-set intersection and union (and/or in Rust and JavaScript, and_/or_ in Python), and locator-only filter containment. AND/OR form new contiguous per-row runs; filters preserve whole matches. See the JavaScript and Python composition examples.

expect text also accepts --not and --timeout MS. click text accepts --button left|middle|right, --alt, --ctrl, --shift, --clicks N, and --timeout MS. highlight text accepts --timeout MS.

Keyboard and mouse

Command	Description
submit [TEXT]	Type text and press Enter.
type TEXT	Type text.
write DATA	Write raw bytes.
key press KEYS...	Press keys.
key down KEYS...	Send keydown events.
key repeat KEYS...	Send repeat events.
key up KEYS...	Send keyup events.
mouse click [X Y] [options]	Click a cell or --on-text TEXT.
mouse move X Y	Move the pointer.
mouse down X Y [options]	Press a mouse button.
mouse up X Y [options]	Release a mouse button.
mouse drag X1 Y1 X2 Y2 [options]	Drag between cells.
mouse scroll up|down [--amount N]	Scroll.
resize COLS ROWS	Resize the terminal.
signal INT|TERM|KILL|QUIT	Send a signal.
kill	Kill the child process.

Mouse button actions accept --button left|middle|right, --alt, --ctrl, and --shift. Click also accepts --clicks N.

Named keys include arrows, Home, End, PageUp, PageDown, Insert, Delete, Backspace, Tab, Enter, Space, Escape, and F1 through F12. Join modifiers such as Ctrl, Alt, Shift, Super, Meta, or Hyper with +.

Read state

Command	Description
state	Print session state and visible text.
text [--full]	Print terminal text.
cells X Y [W H]	Return cells and styles.
get command	Return the last command.
get output	Return the last command output.
get exit-code	Return the last exit code.
get cwd	Return the working directory.
get cursor	Return the cursor position.
get size	Return the terminal size.
get title	Return the window title.
get clipboard	Return the session clipboard.
get bells	Return the bell count.
get bell-events	Return bell events.

Wait and assert

Command	Description
wait title TEXT [--regex --not --timeout MS]	Wait for a title.
wait clipboard [TEXT] [--regex --timeout MS]	Wait for a clipboard change or match.
wait idle [--timeout MS]	Wait for the screen to stop changing.
wait command [--timeout MS]	Wait for a submitted command.
wait exit [--timeout MS]	Wait for the program to exit.
wait ready [--timeout MS]	Wait for a shell prompt.
wait bell [--timeout MS]	Wait for a bell.
expect title TEXT [--regex --not --timeout MS]	Assert the title.
expect exit-code CODE [--timeout MS]	Assert the last exit code.
expect output TEXT [--regex]	Assert command output.
expect bell COUNT [--timeout MS]	Wait until the cumulative bell count reaches COUNT.
expect snapshot NAME [-u] [--include-style] [--include-title]	Assert a snapshot.

Use wait command after submit, wait exit after run, and text locators for visible state. wait idle only means the screen stopped changing.

Timeout defaults:

Class	Default
text	5 seconds
idle	5 seconds
command	30 seconds
exit	30 seconds
ready	30 seconds

Capture

Command	Description
screenshot [PATH] [-o PATH] [--full] [--zoom N] [--background COLOR | --transparent]	Print text or save SVG or PNG.
record start PATH [options] [--background COLOR | --transparent]	Start APNG, GIF, MP4, or asciinema recording.
record stop	Finish the recording.
get-recording [SESSION] [--config PATH]	Print the automatic asciinema recording.
monitor [--interactive]	Watch a CLI session or send input with --interactive.

record start options: --format, --fps, --speed, --idle-time-limit, --zoom, --background, and --transparent. MP4 requires ffmpeg and does not support transparency. Cast recordings do not support canvas options.

The extension selects the format: .png or .apng, .gif, .mp4, or .cast. --format overrides it.

Record

input	monitor

Diagnostics / trace viewer

Add the following to tui-test.toml to retain failed traces, or use mode = "on" to retain every trace.

[trace]
mode = "on-failure"
directory = "./traces"

Users can open trace.html to review the trace or replay session.cast. Agents should read trace.md first and use trace.json and timeline.json for structured evidence instead of parsing the HTML.

Configuration

Create tui-test.toml:

[profiles.default]
scrollback = 10000

[profiles.default.colors]
background = "#000000"
foreground = "#c0c0c0"
red = "#800000"

[recording]
directory = "./casts"

[trace]
mode = "on-failure"
directory = "./traces"

[diagnostics]
screen-history-limit = 10

The CLI checks the current directory, the platform config directory, then ~/.tui-test. Use --config PATH or TUI_TEST_CONFIG to select a file.

Shells and backends

Shells: bash, zsh, fish, PowerShell, pwsh, cmd, xonsh, elvish, and nushell.

Backends: Alacritty, Ghostty, Rio, and xterm.js. Default: Alacritty.

Exit codes

Code	Meaning
0	Success
1	Wait or assertion failed
2	Invalid usage
3	No session
4	Daemon or IPC error
5	Internal error

Agent commands

Command	Description
usage	Print a short command guide.
agent-context	Print the full command schema as JSON.
skill	Print the complete agent guide.
skill --add	Install the agent skill and local references.

Contributing

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.opensource.microsoft.com.

When you submit a pull request, a CLA bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.

Trademarks

This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft trademarks or logos is subject to and must follow Microsoft's Trademark & Brand Guidelines. Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship. Any use of third-party trademarks or logos are subject to those third-party's policies.