Pre-release

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

tui-test for Python

Control, inspect, and test terminal apps from Python.

Install

pip install --pre tui-test

Python 3.8+ is supported.

Quick start

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

API

TuiTest

TuiTest(session=None, *, backend=None, timeouts=None, profile=None, artifacts=None, recording=None)
Option Type Default
session str TUI_TEST_SESSION or "default"
backend "alacritty" | "ghostty" | "rio" | "xtermjs" "alacritty"
timeouts Timeouts | dict built-in defaults
profile Profile | dict built-in profile
artifacts dict off
recording AutomaticRecording | dict {"mode": "always"}

artifacts["on_failure"] is "svg", "text", or "none". Recording mode is "disabled", "on-failure", or "always".

Properties

Property Type
session str
keyboard keyboard helper
mouse mouse helper

Lifecycle

Method Description
TuiTest.ephemeral(prefix=None, **options) Create a unique session.
await open(**options) Open a shell.
await run(program, *args, **options) Run a program.
await close() Close the session.
await close_quiet() Close without raising.
async with TuiTest() Close on exit.

open() options are shell, backend, cols, rows, cwd, env, wait_ready, restart, retries, profile, 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.

Input

Method Description
await submit(text=None) Type text and press Enter.
await type(text) Type text.
await write(data) Write raw bytes.
await press(*keys) Alias for keyboard.press().
await resize(cols, rows) Resize the terminal.
await signal(name) Send INT, TERM, KILL, or QUIT.
await kill() Kill the child process.

State

Method Returns
await state() State
await text(full=False) str
await cells(x, y, w=1, h=1) list[Cell]
await get_command() str | None
await get_output() str | None
await get_exit_code() int | None
await get_cwd() str | None
await get_cursor() dict
await get_size() dict
await get_title() str | None
await get_clipboard() str
await get_bell_count() int
await get_bell_events() list[BellEvent]

Waits and assertions

Method Description
await wait_title(text, regex=False, not_=False, timeout=None) Wait for a title.
await wait_clipboard(text=None, timeout=None) Wait for a clipboard change or match.
await wait_idle(timeout=None) Wait for the screen to stop changing.
await wait_command(timeout=None) Wait for a submitted command.
await wait_exit(timeout=None) Wait for the program to exit.
await wait_ready(timeout=None) Wait for a shell prompt.
await wait_bell(timeout=None) Wait for a bell.
await expect_title(text, regex=False, not_=False, timeout=None) Assert the title.
await expect_exit_code(code, timeout=None) Assert the last exit code.
await expect_output(text, regex=False) Assert command output.
await expect_bell_count(count, timeout=None) Wait until the cumulative bell count reaches count.
await expect_snapshot(name, **options) Assert or update a snapshot.

wait_clipboard() waits for the next change. A string matches text. A compiled re.Pattern matches a regular expression.

Snapshot options are update, include_colors, and include_title.

Capture

Method Description
await screenshot(path=None, full=False, zoom=None) Return text or save SVG.
await start_recording(path, **options) Start APNG, GIF, MP4, or asciinema recording.
await stop_recording() Finish the recording and return its path.

Recording options are format, fps, speed, idle_time_limit, and zoom. MP4 requires ffmpeg.

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

Locator

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

Create a locator

Method Options
terminal.get_by_text(text, **options) regex, full, whitespace
terminal.get_by_style(style, **options) full
locator.get_by_text(text, **options) regex, full, whitespace, direction
locator.get_by_style(style, **options) full, direction

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.

Select matches

Method Description
any() Keep all matches.
unique() Require one match.
first() Select the first match.
last() Select the last match.
nth(index) Select a zero-based match.

Read and act

Method Description
await locations() Return all selected locations.
await location() Return one location.
await count() Return the current count.
await all() Return one locator per current match.
await wait(state="visible", timeout=None) Wait for "visible" or "hidden".
await expect(not_=False, timeout=None) Assert the locator.
await click(**options) Click the middle cell.
await highlight(timeout=None) Highlight matches.

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.

Keyboard

Method Description
await keyboard.press(*keys) Press keys.
await keyboard.down(*keys) Send keydown events.
await keyboard.repeat(*keys) Send repeat events.
await keyboard.up(*keys) Send keyup events. 
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 +.

Mouse

Coordinates are zero-based terminal cells.

Method Description
await mouse.click(x=None, y=None, **options) Click a cell or on_text.
await mouse.move(x, y) Move the pointer.
await mouse.down(x, y, **options) Press a button.
await mouse.up(x, y, **options) Release a button.
await mouse.drag(x1, y1, x2, y2, **options) Drag between cells.
await mouse.scroll("up" | "down", amount=3) Scroll.

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)

Module functions

Function Description
await sessions() List sessions in this process.
await close_all() Close all sessions in this process.
await get_recording(session=None) Return an automatic asciinema recording.
unique_session(prefix=None) Create a unique session name.

Test helpers

Import from tui_test.testing.

Function Description
await create_terminal(**options) Create, open, and track a terminal.
async with terminal(**options) Open and close a terminal.
await close_all_tracked() Close tracked terminals.
set_terminal_defaults(**options) Set suite defaults.
reset_terminal_defaults() Reset suite defaults.
track_terminal(terminal) Track a terminal.
untrack_terminal(terminal) Stop tracking a terminal.
tracked_count() Count tracked terminals.
terminal_snapshot(text) Normalize text for snapshots.

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

Configuration

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": "svg"},
    recording=AutomaticRecording(mode="on-failure", directory="artifacts"),
)

Types

Type Description
State Session state and visible text.
Cell One terminal cell and its style.
TextMatch Matched text, positions, and spans.
TextStyle Locator style fields.
Profile Scrollback and colors.
Timeouts Text, idle, command, exit, and ready timeouts.
AutomaticRecording Automatic recording mode and directory.
Colors Terminal palette.
MouseButton "left", "middle", or "right".
TextPosition, TextSpan Match coordinates.

__version__ contains the package version.

Errors

Error Exit code
ExpectationError 1
UsageError 2
NoSessionError 3
InternalError 5

All errors extend TuiTestError. Expectation errors can include terminal.text and terminal.screenshot.

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

Project links

Data verified by PyPI on Sep 1, 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:
Latest release

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 Sep 1, 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.0b3.tar.gz (4.2 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.0b3-cp38-abi3-win_amd64.whl (6.5 MB view details)

Uploaded CPython 3.8+Windows x86-64

tui_test-0.1.0b3-cp38-abi3-musllinux_1_2_x86_64.whl (13.1 MB view details)

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

tui_test-0.1.0b3-cp38-abi3-musllinux_1_2_aarch64.whl (12.6 MB view details)

Uploaded CPython 3.8+musllinux: musl 1.2+ ARM64

tui_test-0.1.0b3-cp38-abi3-manylinux_2_28_x86_64.whl (6.5 MB view details)

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

tui_test-0.1.0b3-cp38-abi3-manylinux_2_28_aarch64.whl (6.0 MB view details)

Uploaded CPython 3.8+manylinux: glibc 2.28+ ARM64

tui_test-0.1.0b3-cp38-abi3-macosx_11_0_arm64.whl (5.7 MB view details)

Uploaded CPython 3.8+macOS 11.0+ ARM64

tui_test-0.1.0b3-cp38-abi3-macosx_10_12_x86_64.whl (6.0 MB view details)

Uploaded CPython 3.8+macOS 10.12+ x86-64

File details

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

File metadata

  • Download URL: tui_test-0.1.0b3.tar.gz
  • Upload date:
  • Size: 4.2 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.0b3.tar.gz
Algorithm Hash digest
SHA256 6afa857e55db635a00018a53a89ad3dc7d3105754629eececa12aea1a991b211
MD5 110b983d20b78d3e3cc3fa54df7a258c
BLAKE2b-256 1bcb9ae4ca87a3ba81d54d7718a0606fdb25b77399490078e1d71cbbcee78d20

See more details on using hashes here.

Provenance

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

File metadata

  • Download URL: tui_test-0.1.0b3-cp38-abi3-win_amd64.whl
  • Upload date:
  • Size: 6.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.0b3-cp38-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 6205601815e7fe4b8efbd235249ea7ecad2b61004faea76eb2e62b878a9bb16b
MD5 a54f98c70d78160fecbdbbabced2ce7e
BLAKE2b-256 86429a2011004cfbbb7541b67f663bc28b972793936dd2a6be819144cee3d33f

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for tui_test-0.1.0b3-cp38-abi3-musllinux_1_2_x86_64.whl
Algorithm Hash digest
SHA256 824d2e4210093edf9cb75299e668fd925a40351deb5f7e9004ef89acbd061d93
MD5 57cd1a6b1c4df90fcc07f95dac6ea06d
BLAKE2b-256 449bda8a189e520b905afca6ac04a7277d4c11562d6d6fc2e3db1b1793122035

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for tui_test-0.1.0b3-cp38-abi3-musllinux_1_2_aarch64.whl
Algorithm Hash digest
SHA256 804a200a9a2183187e4a55ac2aba67e1319242add81584c57734bd6c81ed8aec
MD5 d06417e2e0701811a7b61f83527b19aa
BLAKE2b-256 8951d51efeb35ff9d8c8b63c9f1e2650fde90a171a1843f7dd63f2b3a163adbc

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for tui_test-0.1.0b3-cp38-abi3-manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 4e74c02cce7f5a7dc0b97dce9523d21e01a7d450de0e161a6da5150bf6bb03f7
MD5 b41b05b02583d0082cdcbd2554f095f2
BLAKE2b-256 f42442bca975f7b00ed1559fe5a97212da64de77725de369a082a8d3a919a753

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for tui_test-0.1.0b3-cp38-abi3-manylinux_2_28_aarch64.whl
Algorithm Hash digest
SHA256 e68f5dea6fb9b81569bd811df941b7283148e0147cf50cf4ac9762922f55083f
MD5 981b903db79e206a2e828e73cf5dc0d0
BLAKE2b-256 1af3eeba9a29226e93f5b5ad464e0057f8dea2b3379e4eb845449a45f7559981

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for tui_test-0.1.0b3-cp38-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 5c0f1d498b85a4ab41ef35d75ad89728afd1337b715c63663e76a9ce791988d4
MD5 27851335c3025fbdf01dcd89f009691f
BLAKE2b-256 629ec170bc7ddc6446da3bfd88a7e3294f3a6c79ebc71d57083ba604f16ee140

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for tui_test-0.1.0b3-cp38-abi3-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 63a740b51cbf189de1e39976c1ccbafc8483a5da67132f1af068c59137251bef
MD5 3aca326a9f3e0ec1df0a82096a167e34
BLAKE2b-256 62ead8a77ef31e2ce979d847f0675549e6e4925a93ba5218075d87f440cfce43

See more details on using hashes here.

Provenance

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

This release
Pre-release

0.1.0b3 This release

8 files

Pre-release

0.1.0b2

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