Crate termlens 

Headless PTY test harness for CLI/TUI applications.

termlens spawns your program in a real pseudo-terminal, feeds its output through a VT emulator into an in-memory screen grid, and lets tests assert and snapshot on the rendered screen instead of raw bytes — Playwright for the terminal.

• It is not an expect-style stream matcher (see rexpect/expectrl).
• It is not an SVG transcript generator for docs (see term-transcript).
• It is: real PTY + emulated screen + snapshot assertions.

Example

use std::time::Duration;
use termlens::{Key, Terminal};

let mut t = Terminal::builder()
    .size(80, 24)
    .env("TERM", "xterm-256color") // the default; shown for completeness
    .timeout(Duration::from_secs(10))
    .args(["-c", r#"read line; echo "got: $line"; read quit"#])
    .spawn("sh")?;

t.send_str("hello");
t.send(Key::Enter);
t.wait_until(|screen| screen.contains("got: hello"))?;

t.send(Key::Enter); // release `read quit`; the script finishes
let status = t.wait_exit()?;
assert!(status.success());

Every wait_* call runs under a deadline (builder timeout, default 5s), and a timeout error embeds the screen so a CI log alone shows what the application was displaying. A background reader thread drains the PTY continuously — no output is lost between waits.

With the default insta feature, snapshot-test whole screens:

insta::assert_snapshot!(t.screen());        // plain insta…
termlens::assert_screen_snapshot!(t.screen()); // …or the bundled macro

Re-exports

pub use insta;

Macros

assert_screen_snapshot

Snapshot-assert anything that displays like a Screen.

Structs

Cell

One cell of the screen grid.

ExitStatus

Exit status of the child process.

Screen

An immutable snapshot of the terminal screen.

Style

Visual attributes of a Cell.

Terminal

A program running inside a real PTY, observed through an emulated screen.

TerminalBuilder

Configures and spawns a Terminal.

Enums

Color

A terminal color, as reported by the emulator.

Error

Errors returned by Terminal operations.

Key

A key press to send to the terminal.

Type Aliases

Result

Convenience alias for std::result::Result<T, termlens::Error>.