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 lab_integration::Lab;
pub use lab_integration::LabConfig;
pub use lab_integration::LabOutput;
pub use lab_integration::LabSession;
pub use lab_integration::Recording;
pub use lab_integration::ReplayResult;
pub use lab_integration::assert_outputs_match;
pub use lab_integration::lab_recordings_total;
pub use lab_integration::lab_replays_total;
pub use time_travel_inspector::TimeTravelInspector;
pub use benchmark_gate::BenchmarkGate;
pub use benchmark_gate::GateResult;
pub use benchmark_gate::Measurement;
pub use benchmark_gate::MetricVerdict;
pub use benchmark_gate::Threshold;
pub use rollout_scorecard::RolloutEvidenceBundle;
pub use rollout_scorecard::RolloutScorecard;
pub use rollout_scorecard::RolloutScorecardConfig;
pub use rollout_scorecard::RolloutSummary;
pub use rollout_scorecard::RolloutVerdict;
pub use shadow_run::ShadowRun;
pub use shadow_run::ShadowRunConfig;
pub use shadow_run::ShadowRunResult;
pub use shadow_run::ShadowVerdict;

Modules§

artifact_manifest: Artifact manifests, retention, redaction, and size discipline (bd-2tg0i).
asciicast: Asciicast v2 session recording for FrankenTUI.
baseline_capture: Deterministic baseline capture for performance measurement (bd-760ih).
benchmark_gate: Benchmark gate enforcement with structured evidence.
buffer: Buffer grid storage.
cell: Cell types and invariants.
cost_surface: Render pipeline cost surface mapping (bd-vtor0).
determinism: Deterministic fixtures for tests and E2E harnesses.
doctor_cost_profile: Doctor workflow cost profiling (bd-qbbkv).
doctor_topology: Doctor supervision topology for Asupersync migration (bd-1889t).
failure_signatures: Failure signatures and replay-friendly log quality contracts (bd-xl1c4).
fixture_runner: Fixture runner: executes FixtureSpec workloads and produces BaselineRecords (bd-muv6p).
fixture_suite: Deterministic macrobenchmark and replay fixture suites (bd-muv6p).
flicker_detection: Flicker/Tear Detection Harness for FrankenTUI.
frame_comparison: Golden frame comparison for deterministic replay verification (bd-3mjjt.3).
golden: Golden Output Harness for deterministic testing and isomorphism proofs.
hdd: Hierarchical Delta Debugging (HDD) for structured inputs.
hotspot_extraction: Hotspot extraction and profiling infrastructure (bd-p8i4s).
input_storm: Input Storm Generator for Fault Injection Testing (bd-1pys5.1)
lab_integration: FrankenLab integration: deterministic model simulation with LabScenario.
layout_reuse: Layout and text reuse strategy with strict invalidation contracts (bd-dwrhv).
optimization_policy: Optimization admission policy and opportunity scoring (bd-dyr5a).
presenter_equivalence: Presenter equivalence rules and state-churn minimization model (bd-ddruy).
proof_oracle: Behavior-preservation proof oracles for optimization validation (bd-js3c3).
proptest_support: Shared proptest strategies for cross-crate property tests.
render_certificate: Render-skip certificate design and correctness model (bd-2dlqr).
resize_storm: Resize Storm Generator + Replay Harness (bd-1rz0.15)
rollout_runbook: Rollout runbook: executable documentation for the Asupersync migration (bd-132iq).
rollout_scorecard: Rollout go/no-go scorecard for the Asupersync migration (bd-2crbt).
shadow_run: Shadow-run comparison harness for validating execution-path equivalence.
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.
validation_matrix: Comprehensive validation matrix and logging contract for performance work (bd-pou7j).

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.