microsoft/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 · Quick start · AI agents · API references · Configuration

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

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.

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

The CLI and libraries expose the same terminal actions. Python, JavaScript, Rust, and Go sessions run in-process and do not require the CLI. See Go installation for the Go binding's native build requirement.

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

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

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

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

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

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

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.

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.

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 +.

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:

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.

input	monitor

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.

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: bash, zsh, fish, PowerShell, pwsh, cmd, xonsh, elvish, and nushell.

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

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.

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.