Crate ftui_harness

Expand description

Snapshot/golden testing and time-travel debugging for FrankenTUI.

Snapshot testing: Captures Buffer output as text, compares against stored .snap files.
Time-travel debugging: Records compressed frame snapshots for rewind inspection.

Captures Buffer output as plain text or ANSI-styled text, compares against stored snapshots, and shows diffs on mismatch.

§Role in FrankenTUI

ftui-harness is the verification layer. It powers snapshot tests, time-travel debugging, and deterministic rendering checks used across the workspace.

§How it fits in the system

The harness is not the primary demo app (use ftui-demo-showcase for that). Instead, it is used by tests and CI to validate the behavior of render, widgets, and runtime under controlled conditions.

§Quick Start

use ftui_harness::{assert_snapshot, MatchMode};

#[test]
fn my_widget_renders_correctly() {
    let mut buf = Buffer::new(10, 3);
    // ... render widget into buf ...
    assert_snapshot!("my_widget_basic", &buf);
}

§Updating Snapshots

Run tests with BLESS=1 to create or update snapshot files:

BLESS=1 cargo test

Snapshot files are stored under tests/snapshots/ relative to the crate’s CARGO_MANIFEST_DIR.

Re-exports§

pub use determinism::DeterminismFixture;
pub use determinism::JsonValue;
pub use determinism::LabScenario;
pub use determinism::LabScenarioContext;
pub use determinism::LabScenarioResult;
pub use determinism::LabScenarioRun;
pub use determinism::TestJsonlLogger;
pub use determinism::lab_scenarios_run_total;
pub use time_travel_inspector::TimeTravelInspector;

Modules§

asciicast: Asciicast v2 session recording for FrankenTUI.
buffer: Buffer grid storage.
cell: Cell types and invariants.
determinism: Deterministic fixtures for tests and E2E harnesses.
flicker_detection: Flicker/Tear Detection Harness for FrankenTUI.
golden: Golden Output Harness for deterministic testing and isomorphism proofs.
hdd: Hierarchical Delta Debugging (HDD) for structured inputs.
input_storm: Input Storm Generator for Fault Injection Testing (bd-1pys5.1)
resize_storm: Resize Storm Generator + Replay Harness (bd-1rz0.15)
terminal_model: Simplified terminal model for testing presenter output.
time_travel: Time-travel debugging with frame snapshots.
time_travel_inspector: Simple debug UI for inspecting TimeTravel recordings.
trace_replay: Render-trace replay harness.

Macros§

assert_snapshot: Assert that a buffer matches a stored snapshot (plain text).
assert_snapshot_ansi: Assert that a buffer matches a stored ANSI snapshot (with style info).

Structs§

ProfileSnapshot: Snapshot output captured for a specific profile.
Rect: A rectangle for scissor regions, layout bounds, and hit testing.

Enums§

MatchMode: Comparison mode for snapshot testing.
ProfileCompareMode: Comparison mode for cross-profile output checks.

Functions§

assert_buffer_snapshot: Assert that a buffer’s text representation matches a stored snapshot.
assert_buffer_snapshot_ansi: Assert that a buffer’s ANSI-styled representation matches a stored snapshot.
buffer_to_ansi: Convert a Buffer to text with inline ANSI escape codes.
buffer_to_text: Convert a Buffer to a plain text string.
buffer_to_text_with_pool: Convert a Buffer to a plain text string, resolving grapheme pool references.
current_test_profile: Resolve the active test profile from the environment.
diff_text: Compute a simple line-by-line diff between two text strings.
profile_matrix_text: Run a test closure across multiple profiles and optionally compare outputs.
profile_matrix_text_with_options: Profile matrix runner with explicit comparison options.