Snapshot Testing

FrankenTUI uses insta  for visual snapshot testing. Every screen in the demo showcase has a blessed baseline; running cargo test -p ftui-demo-showcase renders the screens and fails if any frame diverges from its baseline.

This is a how-to. If you’re new to insta, the short version is: tests compare frame text against a stored .snap file, and BLESS=1 or cargo insta review is how you accept a change. If you’re new to the FrankenTUI showcase, read overview first.

The audience is anyone making a change that affects rendering — a widget tweak, a layout fix, a style update, a new screen. If your change changes pixels, you’ll need to re-bless and review.

Motivation

Rendering regressions are hard to catch with unit tests alone. A subtle off-by-one in the presenter, a broken UTF-8 width calculation, a style leak across widgets — all of these look correct under unit tests but produce the wrong bytes on screen. Snapshot tests catch them because they freeze the rendered output.

The trick is keeping the workflow fast enough that contributors actually run it. insta + BLESS=1 + cargo insta review is designed for that.

Mental model

The three commands

# 1) Run tests — fails if any screen diverges.
cargo test -p ftui-demo-showcase
 
# 2) Accept changes non-interactively (use sparingly).
BLESS=1 cargo test -p ftui-demo-showcase
 
# 3) Review pending changes interactively (preferred).
cargo insta review

Most of the time you run (1) to check, (3) to review accepted changes, and commit the resulting .snap files. BLESS=1 is useful in CI or when you’re certain the diffs are correct and you don’t want to scroll through them individually.

The review workflow

cargo test -p ftui-demo-showcase

cargo insta review

cargo test -p ftui-demo-showcase

git add crates/ftui-demo-showcase/src/snapshots/
git add <your code changes>
git commit

When to use BLESS=1 directly

BLESS=1 cargo test -p ftui-demo-showcase skips the review step and overwrites every divergent baseline. Use it when:

• You are adding a new screen and its baseline doesn’t exist yet.
• You made a workspace-wide cosmetic change (e.g. a font metric update) and you’ve already manually verified the diffs are uniform.
• You’re scripting a CI job that regenerates baselines on a named branch.

Otherwise prefer cargo insta review so you actually see the diffs.

Committing snapshots

Snapshot files live under crates/ftui-demo-showcase/src/snapshots/. They are plain text .snap files — diff-friendly, grep-able, and small enough to commit without LFS.

A typical commit looks like:

commit abc123
Author: you

    widgets: fix Table hover style leak

    The hover transition was missing a CUSUM reset so the style leaked
    to the adjacent row on fast pointer movement.

 crates/ftui-widgets/src/table.rs               |  4 ++
 crates/ftui-demo-showcase/src/snapshots/…     | 12 ++++--

Keep snapshot diffs reviewable by keeping code diffs small.

Running the showcase E2E

For full-showcase end-to-end runs under deterministic fixtures:

E2E_DETERMINISTIC=1 E2E_SEED=42 ./scripts/demo_showcase_e2e.sh

This runs the showcase binary against a scripted input sequence with a fixed PRNG seed, captures frames at canonical tick points, and compares them against baselines. Used in CI as a determinism gate.

Pitfalls

Where next