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", *, timeouts=None, artifacts=None) mirrors the cli: open / run, type / write, submit, press / keys, 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, screenshot, wait_text / wait_title / wait_idle / wait_command / wait_exit / wait_ready, expect_text / expect_title / expect_exit_code / expect_output / expect_snapshot, close, and close_quiet.

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

open() and run() accept wait_ready=, retries=, and timeouts=. The timeout classes are text, idle, command, exit, and ready; timeouts= sets session defaults, the constructor takes the same Timeouts (or a dict) as a client-wide default. Unknown class names 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 (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.

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 10, 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 10, 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.0b1.tar.gz (1.7 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.0b1-cp38-abi3-win_arm64.whl (3.3 MB view details)

Uploaded CPython 3.8+Windows ARM64

tui_test-0.1.0b1-cp38-abi3-win_amd64.whl (3.5 MB view details)

Uploaded CPython 3.8+Windows x86-64

tui_test-0.1.0b1-cp38-abi3-musllinux_1_2_x86_64.whl (3.5 MB view details)

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

tui_test-0.1.0b1-cp38-abi3-musllinux_1_2_aarch64.whl (3.4 MB view details)

Uploaded CPython 3.8+musllinux: musl 1.2+ ARM64

tui_test-0.1.0b1-cp38-abi3-manylinux_2_28_x86_64.whl (3.3 MB view details)

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

tui_test-0.1.0b1-cp38-abi3-manylinux_2_28_aarch64.whl (3.2 MB view details)

Uploaded CPython 3.8+manylinux: glibc 2.28+ ARM64

tui_test-0.1.0b1-cp38-abi3-macosx_11_0_arm64.whl (3.1 MB view details)

Uploaded CPython 3.8+macOS 11.0+ ARM64

tui_test-0.1.0b1-cp38-abi3-macosx_10_12_x86_64.whl (3.2 MB view details)

Uploaded CPython 3.8+macOS 10.12+ x86-64

File details

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

File metadata

  • Download URL: tui_test-0.1.0b1.tar.gz
  • Upload date:
  • Size: 1.7 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.0b1.tar.gz
Algorithm Hash digest
SHA256 111ee2847a5099ea61edcb58ce83fc7fdb0259c3d8eacddfec7cf0dbcd43e788
MD5 d0f96a7652543554aef6e6f697d0d5ca
BLAKE2b-256 8161566da3abba95aa16ddaf57c489c363bf8206de5bbb494a19e31c1f2be755

See more details on using hashes here.

Provenance

The following attestation bundles were made for tui_test-0.1.0b1.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.0b1-cp38-abi3-win_arm64.whl.

File metadata

  • Download URL: tui_test-0.1.0b1-cp38-abi3-win_arm64.whl
  • Upload date:
  • Size: 3.3 MB
  • Tags: CPython 3.8+, Windows ARM64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for tui_test-0.1.0b1-cp38-abi3-win_arm64.whl
Algorithm Hash digest
SHA256 ed61fb5009f601da29df22225870e0a522e490ac03af7721a09b9c8db6fe1ad1
MD5 80a05479421043a6c96b67a8e638aa23
BLAKE2b-256 3e7a7c1b83e1be6bf6ac7878215bcc758c6fed467f22e9fae0ba7c05a04db3ff

See more details on using hashes here.

Provenance

The following attestation bundles were made for tui_test-0.1.0b1-cp38-abi3-win_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.0b1-cp38-abi3-win_amd64.whl.

File metadata

  • Download URL: tui_test-0.1.0b1-cp38-abi3-win_amd64.whl
  • Upload date:
  • Size: 3.5 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.0b1-cp38-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 97f64bc54053a7edce8cbd093a1727c4a8cc69656a617f0dab6faf1a7f6316e8
MD5 150665b736883bd062d7c086b5cfb882
BLAKE2b-256 0fd060050cc3489b0a083afe046ff51a488231a471d5792b1599d231e3725a18

See more details on using hashes here.

Provenance

The following attestation bundles were made for tui_test-0.1.0b1-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.0b1-cp38-abi3-musllinux_1_2_x86_64.whl.

File metadata

File hashes

Hashes for tui_test-0.1.0b1-cp38-abi3-musllinux_1_2_x86_64.whl
Algorithm Hash digest
SHA256 211e478d9ccd268b248fb71acc6b03e29949fd71f77519f5b4b2d654b5ab59e3
MD5 c902e1284ffb6f07dd44e44f5194078d
BLAKE2b-256 451c900ac1e085e530ea7bc013a81f03d8c95d2d8a88e9e4704f0399a7cc95ff

See more details on using hashes here.

Provenance

The following attestation bundles were made for tui_test-0.1.0b1-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.0b1-cp38-abi3-musllinux_1_2_aarch64.whl.

File metadata

File hashes

Hashes for tui_test-0.1.0b1-cp38-abi3-musllinux_1_2_aarch64.whl
Algorithm Hash digest
SHA256 5219462c7e5104d923bb6b2129a8087ed15ee8053f054681e93fac3f2cad30e5
MD5 58d8bdabda78814775227911ad9080de
BLAKE2b-256 c445e19ee276c7cab02b19ed53fefc140dc0eea01956167b5629957143a5b3a3

See more details on using hashes here.

Provenance

The following attestation bundles were made for tui_test-0.1.0b1-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.0b1-cp38-abi3-manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for tui_test-0.1.0b1-cp38-abi3-manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 bbc233966c62f9dc0d1f62c1c8435cc98efb429ea174aa5c9d6a075a892a2a6c
MD5 6f52c68f91b31fe180eec28182d5708e
BLAKE2b-256 c3a9f35a946f1872ccc030a7519b8772f3738c4ca29589868fd55ba26cf5add4

See more details on using hashes here.

Provenance

The following attestation bundles were made for tui_test-0.1.0b1-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.0b1-cp38-abi3-manylinux_2_28_aarch64.whl.

File metadata

File hashes

Hashes for tui_test-0.1.0b1-cp38-abi3-manylinux_2_28_aarch64.whl
Algorithm Hash digest
SHA256 d3856f9825266b8e5cddd30b7bfda7e3cfde5c6925dca39240d79fdbd9e488f8
MD5 f3e26bd258633b3bd0e325d8f4d06a25
BLAKE2b-256 6d67f316db2c9dbe23bc6cf5c43d8231d5b44843aed10dd76680764c866b31b7

See more details on using hashes here.

Provenance

The following attestation bundles were made for tui_test-0.1.0b1-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.0b1-cp38-abi3-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for tui_test-0.1.0b1-cp38-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 008c27897160363fe95edf0bda8245c3a0beaee9186bb2eec9f9c17b5ddc2df3
MD5 c7029d9227d86b09acd3465eb3cd5091
BLAKE2b-256 7d572ebc75580ac5c35da734baeefaf9c7187ee89e3dd70cd597ca9a279ceadd

See more details on using hashes here.

Provenance

The following attestation bundles were made for tui_test-0.1.0b1-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.0b1-cp38-abi3-macosx_10_12_x86_64.whl.

File metadata

File hashes

Hashes for tui_test-0.1.0b1-cp38-abi3-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 a98180ab637e62e010221a745fcb9d49aa9332c35038fc85251d53c8aa64599d
MD5 0d0d95efd0f91058bc3e473eeecf950d
BLAKE2b-256 053210995f27b0b38a150172bcc6a2467dab958909014a486984b3e8cf67fa95

See more details on using hashes here.

Provenance

The following attestation bundles were made for tui_test-0.1.0b1-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

Pre-release

0.1.0b2

8 files

This release
Pre-release

0.1.0b1 This release

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