Control, inspect, and test terminal apps from Python.

For scope anchors, whole-match style, relative queries, and trace completion, see examples/parity.py.

from tui_test import ExecutionContext, TextAnchor, TextScope, TextStyle

save = terminal.get_by_text(
    "Save", scope=TextScope(after=TextAnchor("Start"), before=TextAnchor("End")),
).with_style(TextStyle(bold=True))
choice = save.relative_to(
    terminal.get_by_text("Header"), "after",
).with_style(TextStyle(italic=False)).or_(terminal.get_by_link("test:save"))

TextAnchor accepts text, regex, and occurrence. Occurrence defaults to "unique"; alternatives are "any", "first", "last", or a zero-based integer. with_style tests each whole match. It ignores blank cells when visible characters exist. It supports text, style, and link locators. Rust rejects scope or whole-match style on composite nodes. Apply these fields to the operands before composition. It does not replace and_(terminal.get_by_style(...)), which intersects cells. relative_to(parent, direction="within") also accepts "after" and "before". The parent must belong to the same TuiTest instance. Locator methods copy options and leave the original query unchanged.

The constructor and open/run accept context=ExecutionContext(...). Context fields are operation_name, diagnostic_context, artifacts, trace, and screen_history_limit. diagnostic_context maps string keys to string values. The engine sanitizes and limits those fields before it writes them. Per-call fields override constructor fields for that spawn only. open and run also accept recording=AutomaticRecording(directory=...). An explicit AutomaticRecording() restores the engine's default directory. AutomaticRecording.mode accepts "disabled", "on-failure", or "always" in the runtime API. The default mode is "disabled". This controls automatic casts without a trace. Explicit trace options take precedence over this mode. The CLI configuration still permits only recording.directory.

await terminal.finish_trace(failed=False) completes the trace and keeps the terminal open. await terminal.interrupt() cancels pending operations and terminates the child without an operation queue wait. It does not send a keyboard interrupt. Later waits report cancellation until restart or close. An absent session produces NoSessionError. Call close() afterward to release the named session. Use sessions() to check whether a named session is open. OpenResult["recording"] supplies the automatic recording path. get_recording(name) reads current or retained recording content. packed_screen(full=False) returns an owned, read-only UTF-8 memoryview, columns, and rows. locator.highlight_matches(timeout=...) returns the highlighted matches. The existing highlight() method still returns None. expect_snapshot(name, cwd=...) accepts an explicit working directory for snapshot files.

Run the example from the repository root:

PYTHONPATH=bindings/python/src python3 bindings/python/examples/parity.py

The example creates trace artifacts under artifacts/parity-python. Set TUI_TEST_PARITY_ARTIFACTS to choose another directory. Artifacts can contain terminal text.

pip install tui-test

Python 3.8+ is supported.

The wheel contains an ordinary shared library. Python uses generated ctypes declarations for its typed C ABI. The package has no Python native extension.

Set TUI_TEST_NATIVE_LIBRARY to an absolute library path to override the bundled library. The loader checks the ABI version before the first operation.

Install Rust 1.90 or later and the build dependencies for the supported terminal backends. Build a wheel with the standard Python build frontend:

python -m pip install build
env -u CARGO_TARGET_DIR python -m build bindings/python

The build uses setuptools-rust with Binding.NoBinding. Wheels use py3-none-<platform> tags. The source distribution includes the shared ABI, the Rust engine, their assets, and the Cargo configuration that separates backend symbols. Source builds need Cargo dependency access.

For cross builds, set CARGO_BUILD_TARGET and pass -C--build-option=--plat-name=<platform> to python -m build --wheel. Build Linux release wheels in the required manylinux or musllinux container. Use auditwheel repair before publication. Setuptools-rust disables static libc linkage for musl shared libraries.

For a checkout, use the shared library directly:

env -u CARGO_TARGET_DIR cargo build -p tui-test-ffi
PYTHONPATH=bindings/python/src \
TUI_TEST_NATIVE_LIBRARY="$PWD/target/debug/libtui_test_ffi.dylib" \
python bindings/python/examples/shared_library.py

Use libtui_test_ffi.so on Linux or tui_test_ffi.dll on Windows. The example proves that a copied screen remains valid after the session closes.

Each asynchronous call uses a separate worker thread. A blocked wait cannot prevent close() from interrupting waits. Cancellation releases each native result when its call returns.

Cancellation stops the Python await, not the native operation. A canceled open(), run(), or restart() can still complete. The adapter does not close the session automatically after cancellation. This preserves any replacement session with the same name. The caller remains responsible for explicit session cleanup; cancellation does not confirm that a spawn stopped.

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()
    await terminal.get_by_text("Done").expect()

TuiTest(session=None, *, backend=None, timeouts=None, profile=None, screen_history_limit=None, artifacts=None, recording=None)

Set trace.mode to "on" for every session or "on-failure" for failures. Users can open trace.html; agents should read trace.md, trace.json, and timeline.json.

artifacts["on_failure"] selects "none", "text", "html", or "all". Use include_recording to include the cast in failure artifacts.

open() options are shell, backend, cols, rows, cwd, env, wait_ready, restart, retries, profile, style, and timeouts. run() accepts the same options except shell.

The default size is 80 by 30. Timeout defaults are 5 seconds for text and idle, and 30 seconds for command, exit, and ready.

scroll(lines) accepts integers from -2147483648 through 2147483647. Positive values show older output. Negative values move toward the live screen. Zero leaves the viewport unchanged. Movement stops at the available history boundaries. get_viewport() returns a Viewport dictionary with offset and history integer fields. Both fields count rows. An offset of zero means the live screen.

Visible text, locators, and captures use this viewport. text(full=True) remains independent: it returns history plus the live screen. New output preserves the historical view until retained history expires. Keyboard input returns to the live screen. Mouse input and historical locator clicks fail while the viewport shows history. Call scroll_to_bottom() before mouse input. This API is separate from mouse.scroll().

get_cursor() and State.cursor retain the application cursor coordinates. Captures project that cursor into the viewport and hide it outside the view. Raster recordings capture viewport changes. Asciicast remains a PTY stream.

await terminal.scroll_to_top()
print(await terminal.get_viewport())
print(await terminal.text())
print(await terminal.text(full=True))
await terminal.scroll(-2)
await terminal.scroll_to_bottom()

Native assertions accept timeout in milliseconds and use the text timeout by default. Palette expectations use a dictionary of indices and colors.

wait_clipboard() waits for the next change. A string matches text. A compiled text re.Pattern uses Python's search() semantics; bytes patterns are rejected.

Snapshot options are update, include_style, and include_title.

Recording options: format, fps, speed, idle_time_limit, zoom, background, and transparent. MP4 requires ffmpeg and does not support transparency.

Asciicast pause and resume return usage errors without changing the recording. Automatic diagnostic recordings and recovery casts remain continuous, including output during pauses.

Raster recording samples the live terminal at fps (default: 30) and preserves active elapsed time until stop. There is no default idle cap or extra final hold. Set idle_time_limit to cap unchanged visual intervals before speed scales playback time. Asciicast remains a timestamped output stream; FPS sampling does not change it.

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

Pass a RenderStyle to the client constructor, open(), or run(). It supports fonts, colors, padding, window controls, borders, shadows, and cursor animation. A per-call style replaces the constructor style. Omitted nested fields use Rust defaults. Explicit False and zero remain unchanged. Restart preserves the resolved style. These settings affect screenshots and raster recordings, not terminal colors or locator assertions.

from tui_test import TuiTest, RenderStyle, WindowStyle, RecordingCursorStyle

terminal = TuiTest.ephemeral(
    style=RenderStyle(
        font_size=24,
        window=WindowStyle(title_bar=False),
        cursor=RecordingCursorStyle(blink=False, blink_interval_ms=250),
    )
)

blink permits application-requested animation; it does not make a steady cursor blink. Each phase uses blink_interval_ms before playback speed scaling. The default values are True and 500. Screenshots always use the visible phase. Run examples/rendering.py for a complete example.

Locators resolve against the latest terminal screen before every read or action.

from tui_test import TextStyle

save = (
    terminal
    .get_by_text("Settings")
    .get_by_text("Save", direction="after")
    .get_by_style(TextStyle(foreground="green"))
    .unique()
)

await save.click()

whitespace is "exact" or "normalize". direction is "within", "after", or "before".

TextStyle fields are foreground, background, bold, dim, italic, underline_style, underline_color, inverse, hidden, strikethrough, and blink.

get_by_link(uri) matches an exact OSC 8 target, not visible URL text; get_by_link("") requires no link. Root style/link selectors find runs within each row. Chained calls with the default within direction check whole matches. Styles skip blanks if visible text exists; links check every cell.

link = terminal.get_by_link("https://example.com")
bold = terminal.get_by_style(TextStyle(bold=True))
bold_link_cells = bold.and_(link)
either = link.or_(terminal.get_by_text("Help"))
sections = terminal.get_by_text("Docs and Help")
contains_link = sections.filter(has=link)
without_old_text = sections.filter(has_not=terminal.get_by_text("old"))
entirely_linked = sections.get_by_link("https://example.com")

and_() keeps shared cells; or_() combines cells without duplicates. Adjacent cells merge within each physical row, even across original matches. Gaps and row breaks split runs. Counts and clicks use these runs; text keeps exact whitespace.

filter accepts only locators. has requires a match inside each candidate; has_not requires none. Both conditions apply when supplied, and the inner match may cover the whole candidate. For partially linked "Docs", filter(has=link) keeps the whole word, get_by_link(uri) rejects it, and and_(link) returns its linked cells.

Use locators from one TuiTest. Composition leaves them unchanged and reads one fresh snapshot when used. Selection order matters: a.first().and_(b) differs from a.and_(b).first(). Any full branch includes scrollback for the whole query. Errors propagate.

click() accepts button, alt, ctrl, shift, clicks, and timeout. button is "left", "middle", or "right".

location() and click() require one match. all() does not wait.

await terminal.keyboard.press("Ctrl+C")
await terminal.keyboard.press("Escape", ":", "w", "q", "Enter")

Named keys include Up, Down, Left, Right, 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 +.

Coordinates are zero-based terminal cells.

Button options are button, alt, ctrl, and shift. Click also accepts on_text and clicks.

await terminal.mouse.click(10, 5, button="right", ctrl=True)

Import from tui_test.testing.

TerminalOptions adds shell, program, session, and prefix to the client and spawn options.

DEFAULT_SHELL is the platform default.

from tui_test.testing import terminal

async with terminal(program=("my-app",)) as app:
    await app.get_by_text("Ready").expect()

from tui_test import AutomaticRecording, Colors, Profile, Timeouts

terminal = TuiTest(
    profile=Profile(
        scrollback=500,
        colors=Colors(foreground="#ffffff", background="#000000"),
    ),
    timeouts=Timeouts(text=10_000, command=60_000),
    artifacts={"dir": "artifacts", "on_failure": "all"},
    trace={"mode": "on-failure", "directory": "artifacts/traces"},
    recording=AutomaticRecording(directory="artifacts/casts"),
)

__version__ contains the package version.

All errors extend TuiTestError. Structured native failures expose details and artifact; expectation errors continue to populate compatibility terminal.text and terminal.screenshot fields. Failure artifacts can contain terminal output, titles, locator operands, and recordings, so review them before uploading.

Sessions are local to the current process and cannot be controlled by the CLI. Cancelling a task does not stop an active terminal operation.