Pre-release

This release is a pre-release and may not be stable for production use.

tui-test (Python)

Python bindings for tui-test; a terminal automation, inspection, assertion, and recording engine written in Rust.

Install

pip install --pre tui-test

Requires Python 3.8+. Wheels are published for common platforms via maturin

Quick start

import asyncio
from tui_test import TuiTest

async def main():
    async with TuiTest() as su:
        await su.open()
        await su.submit("echo hello")
        await su.wait_command()
        await su.expect_text("hello")
        await su.expect_exit_code(0)

asyncio.run(main())

Drive a full-screen TUI:

async with TuiTest("vim-session") as su:
    await su.run("vim", "file.txt")
    await su.wait_idle()
    await su.press("i")
    await su.type("some text")
    await su.press("Escape", ":", "w", "q", "Enter")
    await su.wait_exit()

Errors

Every failure maps to one of the engine's error kinds:

Exception Exit code Meaning
ExpectationError 1 an expect/wait condition was not met
UsageError 2 invalid argument (e.g. a bad regex)
NoSessionError 3 no active session
InternalError 5 internal engine error

All derive from TuiTestError. wait_* and expect_* raise ExpectationError on failure. Assertion errors include the current visible terminal content.

API

TuiTest(session="default", *, backend=None, timeouts=None, profile=None, artifacts=None) mirrors the cli: open / run, type / write, submit, keyboard.press|down|repeat|up, compatibility press, mouse.click|move|down|up|drag|scroll, resize, signal / kill, state, text, cells, get_command / get_output / get_exit_code / get_cwd / get_cursor / get_size / get_title / get_bell_count / get_bell_events, screenshot, start_recording / stop_recording, wait_text / wait_title / wait_idle / wait_command / wait_exit / wait_ready / wait_bell, expect_text / expect_title / expect_exit_code / expect_output / expect_bell_count / expect_snapshot, close, and close_quiet.

keyboard.press() simulates key presses: it sends the normal press input and adds a release only when the negotiated Kitty mode can represent it. keyboard.down() and keyboard.up() simulate explicit keydown and keyup events; keyboard.repeat() simulates repeats. Top-level press() remains a compatibility alias.

Module-level helpers: sessions(), close_all(), get_recording(), unique_session().

open() and run() accept backend=, wait_ready=, restart=, retries=, profile=, and timeouts=. They reuse a live named session unless restart=True is passed. The constructor also accepts backend= and profile= as defaults for later opens and runs. Backend values are "alacritty" (default), "ghostty", and "rio":

terminal = TuiTest(backend="ghostty")
await terminal.open()
await terminal.run("vim", "file.txt", backend="rio")

The native package includes every supported emulator. Profiles are partial; omitted fields use the built-in defaults:

from tui_test import Colors, Profile, TuiTest

terminal = TuiTest(
    profile=Profile(
        scrollback=500,
        colors=Colors(red="#ff0000"),
    )
)

Mappings with the same shape are also accepted. The timeout classes are text, idle, command, exit, and ready; timeouts= sets session defaults, and the constructor takes the same Timeouts (or a dict) as a client-wide default. Unknown fields raise.

TuiTest.ephemeral(prefix=None, **kwargs) binds a client to a unique, process-local session name. artifacts={"dir": ..., "on_failure": ...} attaches the terminal contents to an ExpectationError.

tui_test.testing has helpers for terminal tests: create_terminal, terminal (an async context manager), close_all_tracked, DEFAULT_SHELL, and terminal_snapshot.

from tui_test.testing import terminal

async def test_echo():
    async with terminal() as t:
        await t.submit("echo hi")
        await t.wait_command()
        await t.expect_text("hi")

Each terminal is uniquely named, so parallel workers don't collide. set_terminal_defaults(...) sets suite-wide options (profile, timeouts, artifacts, ...).

Cancellation and recordings

Cancelling a task does not cancel the underlying Rust operation. Operations for single sessoins wait for completion (ex: close(), close_all()).

Closing a session removes it from sessions(), but keeps its recording. get_recording() can read that recording for the rest of the process. The 1024 most recently closed sessions have their recordings retained.

await su.start_recording("demo.png", fps=30, speed=1.0, zoom=0.5)
await su.submit("echo hello")
await su.wait_command()
path = await su.stop_recording()

.png/.apng selects lossless APNG, .gif selects GIF, .mp4 selects MP4, and .cast selects asciicast v2. Pass format= to override extension inference. zoom= scales SVG screenshots and image/video recordings without changing terminal rows or columns. MP4 recording requires ffmpeg to be available on PATH.

Configuration

Variable Purpose
TUI_TEST_SESSION default session name
TUI_TEST_TIMEOUT_<CLASS>_MS fallback timeout for one class (TEXT, IDLE, COMMAND, EXIT, READY)

Project links

Data verified by PyPI on Aug 22, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (0.1.0b3)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for msft_cpendery from gravatar.com msft_cpendery

Credits

Author: Microsoft

GitHub Statistics

Data verified by PyPI on Aug 22, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License

MIT License (MIT)

Requires

Python >=3.8

Tags

terminal pty automation testing tui tui-test

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

tui_test-0.1.0b2.tar.gz (4.0 MB view details)

Uploaded Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

tui_test-0.1.0b2-cp38-abi3-win_amd64.whl (5.7 MB view details)

Uploaded CPython 3.8+Windows x86-64

tui_test-0.1.0b2-cp38-abi3-musllinux_1_2_x86_64.whl (12.3 MB view details)

Uploaded CPython 3.8+musllinux: musl 1.2+ x86-64

tui_test-0.1.0b2-cp38-abi3-musllinux_1_2_aarch64.whl (11.8 MB view details)

Uploaded CPython 3.8+musllinux: musl 1.2+ ARM64

tui_test-0.1.0b2-cp38-abi3-manylinux_2_28_x86_64.whl (5.7 MB view details)

Uploaded CPython 3.8+manylinux: glibc 2.28+ x86-64

tui_test-0.1.0b2-cp38-abi3-manylinux_2_28_aarch64.whl (5.3 MB view details)

Uploaded CPython 3.8+manylinux: glibc 2.28+ ARM64

tui_test-0.1.0b2-cp38-abi3-macosx_11_0_arm64.whl (5.0 MB view details)

Uploaded CPython 3.8+macOS 11.0+ ARM64

tui_test-0.1.0b2-cp38-abi3-macosx_10_12_x86_64.whl (5.3 MB view details)

Uploaded CPython 3.8+macOS 10.12+ x86-64

File details

Details for the file tui_test-0.1.0b2.tar.gz.

File metadata

  • Download URL: tui_test-0.1.0b2.tar.gz
  • Upload date:
  • Size: 4.0 MB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for tui_test-0.1.0b2.tar.gz
Algorithm Hash digest
SHA256 31423f2bbcefed807a3fce699f8e98f93c1e07d793f8f399552c2c0fd67e824b
MD5 100505a5a96aa461ec57fea07c4441a8
BLAKE2b-256 fb6a3dc38c461fd437b6f61355b64cfafd9d2de64f5253198ed7c8e39e2f9321

See more details on using hashes here.

Provenance

The following attestation bundles were made for tui_test-0.1.0b2.tar.gz:

Publisher: release.yml on microsoft/tui-test

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file tui_test-0.1.0b2-cp38-abi3-win_amd64.whl.

File metadata

  • Download URL: tui_test-0.1.0b2-cp38-abi3-win_amd64.whl
  • Upload date:
  • Size: 5.7 MB
  • Tags: CPython 3.8+, Windows x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for tui_test-0.1.0b2-cp38-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 5663d91d8f8222bee4787fcc20cb1f6142272650961d1f9113faae7d4b81c446
MD5 26f23fff386162887d86f50fb04fdbb2
BLAKE2b-256 d66fc110c141f56e19cb4d939dc5acd2555a959c26eaf7fad07c0f50a2538ac0

See more details on using hashes here.

Provenance

The following attestation bundles were made for tui_test-0.1.0b2-cp38-abi3-win_amd64.whl:

Publisher: release.yml on microsoft/tui-test

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file tui_test-0.1.0b2-cp38-abi3-musllinux_1_2_x86_64.whl.

File metadata

File hashes

Hashes for tui_test-0.1.0b2-cp38-abi3-musllinux_1_2_x86_64.whl
Algorithm Hash digest
SHA256 8ff160b6bfb631998d4204f0b028af796f4387004170aad106327265ba5adfea
MD5 8ade70643ffa0d06f124aae11d9f2e45
BLAKE2b-256 6e3790dc807a7354bf903871485cbe08103be3df19575f1df6e86103c6ca442e

See more details on using hashes here.

Provenance

The following attestation bundles were made for tui_test-0.1.0b2-cp38-abi3-musllinux_1_2_x86_64.whl:

Publisher: release.yml on microsoft/tui-test

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file tui_test-0.1.0b2-cp38-abi3-musllinux_1_2_aarch64.whl.

File metadata

File hashes

Hashes for tui_test-0.1.0b2-cp38-abi3-musllinux_1_2_aarch64.whl
Algorithm Hash digest
SHA256 4853a9b8f895e9e30ef3fc53f77e2bc0f5fa5c85fa2885e6635b7ca809454873
MD5 8d9f10e4995dc3697eb341c70dc528ce
BLAKE2b-256 d2ba1578c8b012ab32e811827e1fa5eb5b41974a1a3c6c7a09d1d2428223745e

See more details on using hashes here.

Provenance

The following attestation bundles were made for tui_test-0.1.0b2-cp38-abi3-musllinux_1_2_aarch64.whl:

Publisher: release.yml on microsoft/tui-test

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file tui_test-0.1.0b2-cp38-abi3-manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for tui_test-0.1.0b2-cp38-abi3-manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 f20506efa7f7446e3c08ca55dd27805e5ece7efe90d817d2a05102eedfdaf9f8
MD5 24810b6a713d3781670117b2ec2fbeba
BLAKE2b-256 130101a19a698115bf74e023cbaea4e761e4ce2948b45fe4970c82175d91044b

See more details on using hashes here.

Provenance

The following attestation bundles were made for tui_test-0.1.0b2-cp38-abi3-manylinux_2_28_x86_64.whl:

Publisher: release.yml on microsoft/tui-test

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file tui_test-0.1.0b2-cp38-abi3-manylinux_2_28_aarch64.whl.

File metadata

File hashes

Hashes for tui_test-0.1.0b2-cp38-abi3-manylinux_2_28_aarch64.whl
Algorithm Hash digest
SHA256 17daca3cc2537fc9029261fad919e243960c00ec9061afc0f5f232d585e1964e
MD5 d50c80f7afa6e06a8bd4b380a0aeec89
BLAKE2b-256 dc060139c16e1d6808df51186bd76cf4c16b4f23144598c863af1769a6694ddd

See more details on using hashes here.

Provenance

The following attestation bundles were made for tui_test-0.1.0b2-cp38-abi3-manylinux_2_28_aarch64.whl:

Publisher: release.yml on microsoft/tui-test

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file tui_test-0.1.0b2-cp38-abi3-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for tui_test-0.1.0b2-cp38-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 a40c83206028142a99c57c032a54cd23143934c0f2ae80408140e2fd12fd9c0e
MD5 13234d9ade638f8e0605cb0cc66b675b
BLAKE2b-256 f8e5a4f9f5feefff4fdfc6f866fa0a50d0d412c8a45d91e03ca40ddcb8673471

See more details on using hashes here.

Provenance

The following attestation bundles were made for tui_test-0.1.0b2-cp38-abi3-macosx_11_0_arm64.whl:

Publisher: release.yml on microsoft/tui-test

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file tui_test-0.1.0b2-cp38-abi3-macosx_10_12_x86_64.whl.

File metadata

File hashes

Hashes for tui_test-0.1.0b2-cp38-abi3-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 14883832db4861edaa95772b156b18455604c8725186e268e1bffb62dc7fcf30
MD5 622450107ccbaac8108e7a117374e204
BLAKE2b-256 5ef481df5c96a00c94ef67b8bed9211fabde4c540ff6d8f4b104cdbdd40361dd

See more details on using hashes here.

Provenance

The following attestation bundles were made for tui_test-0.1.0b2-cp38-abi3-macosx_10_12_x86_64.whl:

Publisher: release.yml on microsoft/tui-test

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

Pre-release

0.1.0b3

8 files

This release
Pre-release

0.1.0b2 This release

8 files

Pre-release

0.1.0b1

9 files

Pre-release

0.0.1b1

2 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page