testty

Documentation | API reference

testty is a framework for end-to-end testing of terminal apps. It launches your real app and checks what shows up on screen — text, colors, and highlights — with a single Rust API.

Installation

[dev-dependencies]
testty = "0.9"
tempfile = "3"

Command-line binary

testty also ships a testty command-line front end so projects in any language — not just Rust crates — can drive TUI scenarios, generate schemas, and inspect proof artifacts. Install it with:

cargo install testty

testty run <scenario.yaml> [--bin <BIN>] [--proof <DIR>]
testty schema
testty proof open <html>
testty proof gallery <dir>
testty update

run — execute a scenario file against a TUI binary.
schema — print the JSON schema for scenario files.
proof open — open a single proof report.
proof gallery — build a gallery from a directory of proof reports.
update — update stored scenario snapshots to match current output.

run executes a YAML scenario against a binary and reports pass/fail through the exit code (see YAML scenarios). The remaining verbs (schema, proof open, proof gallery, update) are still stubs: they print a "not yet implemented" notice and exit non-zero until the behavior is wired up.

Capabilities

Reliable • No flaky tests

Auto-wait. wait_for_stable_frame and eventually wait for the screen to settle before asserting, so you never hard-code sleeps.
Screen-first assertions. Check visible text, colors, and highlighted items, with ready-made helpers for tabs, dialogs, and footers.
Full isolation. Each test runs your real binary in its own workspace, so tests never bleed into one another.

Proof you can share

Snapshots. Compare a run against a saved baseline — screen text or pixels.
Reports. Save what each test saw as plain text, a screenshot, an animated GIF, or a self-contained HTML report.

Examples

Write a test

use testty::scenario::Scenario;
use testty::session::PtySessionBuilder;

#[test]
fn tab_switches_view() {
    let temp = tempfile::TempDir::new().unwrap();
    let builder = PtySessionBuilder::new(env!("CARGO_BIN_EXE_myapp"))
        .size(80, 24)
        .workdir(temp.path());

    let scenario = Scenario::new("tab_switch")
        .wait_for_stable_frame(500, 5_000)
        .press_key("Tab")
        .wait_for_stable_frame(300, 3_000)
        .capture();

    let frame = scenario.run(builder).expect("scenario failed");

    testty::recipe::expect_selected_tab(&frame, "Sessions");
    testty::recipe::expect_unselected_tab(&frame, "Projects");
}

cargo test -p my-app --test e2e

Wait for something to appear

use std::time::Duration;

use testty::assertion;
use testty::region::Region;
use testty::scenario::Scenario;

let scenario = Scenario::new("counter")
    .write_text("+++")
    .eventually(
        Duration::from_secs(5),
        Duration::from_millis(50),
        |frame| assertion::match_text_in_region(frame, "Counter: 3", &Region::full(80, 24)),
    )
    .capture();

Compare against a saved baseline

use testty::snapshot::{self, SnapshotConfig};

let config = SnapshotConfig::new("tests/baselines", "tests/artifacts");
snapshot::assert_frame_snapshot_matches(&config, "startup", &frame.all_text())
    .expect("snapshot should match");

Save a shareable report

use std::path::Path;

use testty::proof::html::HtmlBackend;
use testty::proof::junit::JunitBackend;

let (_frame, report) = scenario.run_with_proof(builder).expect("failed");
report.save(&HtmlBackend, Path::new("proof.html")).unwrap();
report.save(&JunitBackend, Path::new("proof.xml")).unwrap();

Run a scenario from YAML — no Rust required

Installing the crate (cargo install testty) provides the testty binary, so projects in any language can drive TUI scenarios with a YAML file:

# scenario.yaml
session:
  bin: ./myapp
  size: [80, 24]
steps:
  - wait_for_stable_frame: { stable_ms: 500, timeout_ms: 5000 }
  - press_key: Tab
expect:
  - selected_tab: Sessions

testty run scenario.yaml

The exit code is the pass/fail signal (0 = passed), so it drops straight into any CI. See YAML scenarios.

Resources

Getting started — install, write your first test, run it
Scenarios — describe a sequence of actions and waits
YAML scenarios — run scenarios from a file with testty run, no Rust required
Assertions — check text, colors, and highlights on screen
Snapshots — compare a test against a saved baseline
Proof pipeline — save what a test saw as text, image, GIF, HTML, or JUnit-XML
Journeys — reusable building blocks for tests
Frame diffing — see what changed between two screens
Examples — runnable example programs
Upgrading — version migration notes
API reference — full generated docs

License

Apache-2.0. See LICENSE.

testty 0.13.2