Today — the macro has two arms and both forward to insta::assert_snapshot! unchanged (crates/termlens/src/lib.rs): assert_screen_snapshot!(screen) and the inline form assert_screen_snapshot!(screen, @"…"). Measured against 0.9.0, a reader who finds it in the docs learns nothing they did not already know from insta, and the README's example uses insta::assert_snapshot!(t.screen()) directly — correctly, since it is the same thing.
Why it is worth fixing — a snapshot of a TUI needs three decisions every time: wait for the picture to settle, snapshot styles or text only, and which screen. insta::assert_snapshot!(t.screen()) makes none of them, which is why the README explains rule 2 of docs/DESIGN.md §2 beside its example. The macro has the name that promises those defaults and delivers an alias. Either it earns the name or it is documented as the pinned-insta-version alias it is; the first is an afternoon and removes a paragraph from every consumer's first test.
Fix — make the macro take the Terminal and bundle the defaults, leaving insta::assert_snapshot!(t.screen()) as the documented low-level spelling:
termlens::assert_screen_snapshot!(t); // = wait_stable(100ms), then with_styles()
termlens::assert_screen_snapshot!(t, styles = false); // text only
termlens::assert_screen_snapshot!(t, after = |s| s.contains("Ready")); // = snapshot_after(pred), styles on
termlens::assert_screen_snapshot!(t, @"inline"); // still accepted
Built on snapshot_after/wait_stable (0.9.0), so the macro adds no waiting logic of its own. styles defaults on because a TUI regression is as often a colour as a character, and the styles: block is what catches it. A Screen argument keeps working for callers who already hold one. Failures come from insta unchanged.
The macro's rustdoc becomes the home for the one-paragraph version of the race rules — the place a beginner actually reads them — and the README example switches to it.
Done when — assert_screen_snapshot!(t) settles, snapshots with styles and fails through insta; the styles =, after = and inline forms work; a Screen argument still works; the README's first example uses it and drops the rule-2 explanation it no longer needs; and tests/readme_example.rs follows.
Today — the macro has two arms and both forward to
insta::assert_snapshot!unchanged (crates/termlens/src/lib.rs):assert_screen_snapshot!(screen)and the inline formassert_screen_snapshot!(screen, @"…"). Measured against 0.9.0, a reader who finds it in the docs learns nothing they did not already know from insta, and the README's example usesinsta::assert_snapshot!(t.screen())directly — correctly, since it is the same thing.Why it is worth fixing — a snapshot of a TUI needs three decisions every time: wait for the picture to settle, snapshot styles or text only, and which screen.
insta::assert_snapshot!(t.screen())makes none of them, which is why the README explains rule 2 ofdocs/DESIGN.md§2 beside its example. The macro has the name that promises those defaults and delivers an alias. Either it earns the name or it is documented as the pinned-insta-version alias it is; the first is an afternoon and removes a paragraph from every consumer's first test.Fix — make the macro take the
Terminaland bundle the defaults, leavinginsta::assert_snapshot!(t.screen())as the documented low-level spelling:Built on
snapshot_after/wait_stable(0.9.0), so the macro adds no waiting logic of its own.stylesdefaults on because a TUI regression is as often a colour as a character, and thestyles:block is what catches it. AScreenargument keeps working for callers who already hold one. Failures come from insta unchanged.The macro's rustdoc becomes the home for the one-paragraph version of the race rules — the place a beginner actually reads them — and the README example switches to it.
Done when —
assert_screen_snapshot!(t)settles, snapshots with styles and fails through insta; thestyles =,after =and inline forms work; aScreenargument still works; the README's first example uses it and drops the rule-2 explanation it no longer needs; andtests/readme_example.rsfollows.