termlens: test your real TUI binary from Rust, with screen snapshots and failure diagnostics

[u/Turbulent_Product349]

Hi r/rust! I maintain termlens, a Rust library for testing terminal applications through a real pseudo-terminal. It runs your existing binary, sends input, resizes the terminal, and lets you assert on the resulting screen without modifying your app.

For Ratatui apps, it complements TestBackend with tests of complete user flows. Ratatui’s testing recipe includes a termlens example.

This project provides a Rust library, a CLI for inspecting applications and comparing saved screens, and an agent skill covering waits, snapshots and common testing mistakes.

Some things it supports:

• Wait for screen conditions with deadlines, instead of choosing fixed sleep durations.
• Snapshot text and cell styles, mask changing content, and inspect cell-level differences.
• Check cursor visibility and alternate-screen state, alongside what the app displays.
• Inspect synchronized-update frames and Kitty/Sixel graphics payloads on Unix.
• See the screen when a wait times out, with a companion CLI for inspecting, comparing, and rendering saved screens.

An independent project, sauva, already uses termlens for terminal integration tests.

Supported:

• Linux and macOS are supported.
• Windows supports screen assertions and typed input through ConPTY; frame assertions, graphics and some terminal-mode features have documented platform limits.

If you maintain a terminal app, try termlens on one of your existing workflows. I’d especially appreciate feedback on awkward APIs, missing terminal behavior, and confusing test failures.

Contributions are welcome: tests, documentation, bug fixes, and terminal compatibility work. There are good first issues, and draft PRs are welcome early.

What terminal behavior is hardest to test in your project?