tui-test

Use tui-test to control and test a real terminal.

Pick an API

Use the library that matches the project. Use the CLI when the terminal must persist across separate commands or be watched with monitor.

CLI and library sessions do not share state.

CLI

tui-test run my-app
tui-test expect text "Ready"
tui-test click text "Continue"
tui-test expect text "Done"
tui-test close

Run tui-test agent-context for exact command and option names.

Python

from tui_test import TuiTest

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()

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();
} finally {
  await terminal.closeQuiet();
}

Locators

Use text and style locators for visible terminal state.

save = (
    terminal
    .get_by_text("Settings")
    .get_by_text("Save", direction="after")
    .unique()
)

await save.click()

• Use first(), last(), nth(), or unique() before an action when text repeats.
• Use get_by_style() or getByStyle() for colors and attributes.
• Use direction="within", "after", or "before" for relative matches.
• Use locations() or count() for immediate reads.
• Use wait(), expect(), or click() when the app may still be changing.

Wait for state

Do not use a fixed sleep when a wait can describe the state.

Keep tests stable

• Give parallel tests unique sessions.
• Use open for shell commands and run for an app.
• Assert the exit code separately from visible text.
• Keep the shell, terminal size, cwd, environment, and timeouts explicit when they affect output.
• Use semantic mouse buttons: left, middle, or right.
• Close every session. Prefer the Python and JavaScript test helpers.

Capture output

Use screenshot for text, SVG, or PNG. SVG, PNG, APNG, and GIF support --background COLOR and --transparent. MP4 supports --background only. Use record for APNG, GIF, MP4, or asciinema. Use recording mode on-failure for test artifacts.

References

• CLI
• Python
• JavaScript
• Rust
• Recipes