tui-test

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, JavaScript, or Go. It works for AI agents that need structured access to terminal state, terminal automation, and terminal ui application testing.

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 | sh

Windows:

irm https://raw.githubusercontent.com/microsoft/tui-test/main/install/install.ps1 | iex

You can also download a binary from GitHub Releases.

Libraries

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

Go, Python, and JavaScript use one native adapter crate. All three use its generated C ABI declarations through purego, ctypes, and Koffi, respectively. Set TUI_TEST_NATIVE_LIBRARY to select a matching library explicitly.

Quick start

The CLI and libraries expose the same terminal actions. Python, JavaScript, Rust, and Go sessions run in-process and do not require the CLI. Released Go modules include the native engine; see Go installation for supported platforms and Linux runtime requirements.

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

Go

package main

import (
    "log"

    "github.com/microsoft/tui-test/bindings/go"
)

func main() {
    terminal, err := tuitest.Ephemeral("example", tuitest.ClientOptions{})
    if err != nil {
        log.Fatal(err)
    }
    defer terminal.CloseQuiet()

    if _, err := terminal.Run("my-app", nil, tuitest.SpawnOptions{}); err != nil {
        log.Fatal(err)
    }
    if err := terminal.GetByText("Ready", tuitest.TextSelectorOptions{}).Expect(tuitest.LocatorExpectOptions{}); err != nil {
        log.Fatal(err)
    }
}

Go installation and API reference

API references

CLI reference

Global options

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

Sessions

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]

Locator options:

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

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

Native scrolling changes the visible viewport without mouse input to the application. New output preserves the historical view. Keyboard input returns to the live screen. Mouse input and historical locator clicks fail until you return to the live screen. Full-text reads remain independent of the viewport. See the history reference, JavaScript example, and Rust example.

Wait and assert

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:

Capture

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

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

Set the appearance of screenshots and recordings with [recording.style]:

[recording.style]
font_size = 18
canvas_background = "#05050a"
canvas_padding = 30

[recording.style.window]
background = "#15151f"
foreground = "#c8c8e0"
divider = "#2a2a3a"

[recording.style.border]
width = 1
color = "#3a3a52"
radius = 12

[profiles.default.colors]
background = "#0b0b12"
foreground = "#d8d8e8"

Profiles override individual keys and inherit the rest from the file. Failure SVGs and HTML report SVGs use the session style. See the style types and defaults for all options. The CLI reference explains profile overrides.

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

Agent commands

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.