Source: context/test-evidence/tui.md

On this page

Test evidence — the terminal front end (src/, tests/, examples/)

Keyed by exact test name, per design-principles §7. A renamed test orphans its entry; python3 scripts/check-comment-runs.py --check-evidence catches a heading that names no test.

A ### heading is a test, and --check-evidence only counts #[test] functions, so it cannot be satisfied by a helper of the same name. Fixtures and helpers that carry an argument get a subordinate #### heading under the tests they serve — unchecked, and deliberately so: there is nothing to orphan, because a renamed helper is found by the compiler.

#tests/grid_frame_agreement.rs — the two front ends draw the same frame

improvise-anr9/s1xw. The divergence this file exists to rule out was real and shipped: GridCache::row_labels was a Vec<String> built by GridLayout::row_label, which slash-joins a multi-level tuple — the exact rendering src/ui/grid.rs::two_row_categories_produce_cross_product_labels asserts must not appear. So the protocol carried a form of the labels the TUI itself considered wrong, and the browser drew Food/Alice where the TUI drew two header columns, with no groups and no collapse indicators.

The shape of the check is the point. Each front end is driven the way it is really driven — the widget into a ratatui buffer, the client through a Snapshot of the same cache's seed() — and the two are compared on what they draw, not on what they were handed. Comparing the caches would be vacuous: it is one cache.

#two_level_rows (helper)

The fixture. Both axes multi-level and grouped — the cross product the slash-join used to flatten, on rows and columns, so the frame carries header levels, repeat suppression, group spans and a collapse state in one fixture.

Two deliberate asymmetries:

#tui_row_headers (helper)

Slices the painted row header by AxisFrame::header_widths, because that is the same rule the widget lays the sub-columns out with (improvise-1125). Reading the widths a second way here would be the very duplication under test. The body ends at the blank space below the grid, or at the rule above the totals strip — which is not a row of the frame.

#tui_header_cells (helper)

Cuts one painted header line by the cache's own col_widths past the row header, for the same reason. Labels are right-aligned into width - 1, so a trim recovers them.

#the_two_front_ends_draw_the_same_row_header

Injected fault, watched fail before keeping: re-introducing the slash-join on either side — labels: vec![rows.item(r).join("/")] in the client's render_model, or rows.item(ri).join("/") in the widget's row header — makes this test fail, naming the row and the two spellings. Both were watched fail.

A group header is one label across the whole row header; a data row is one label per level, and the TUI's slicing puts a group label in the first sub-column, so the comparison joins the non-empty text. The group arm compares the full painted string, glyph and name: a branch that checked only the glyph would pass on any group name whatsoever. indicator is the TUI's glyph spelled out locally so the comparison is against what is really painted rather than against a prefix test.

The tui.len() > 4 precondition exists because a fixture with no group headers and few data rows compares almost nothing.

#the_two_front_ends_draw_the_same_column_header

A separate test because the row-header one drives one arm: a col_levels that stopped suppressing repeats, or a col_groups that emitted one span per column, would sit green behind it (doctrine(one_arm_of_a_symmetric_rule_is_evidence_about_that_arm_only)).

Each header line is cut into columns and compared exactly. A contains would be one-directional: it cannot see a label the browser wrongly blanked (the filter would skip it) and it cannot see one painted under the wrong column.

improvise-gd83 is fixed and THE_MEMBERSHIP_CORRECT_SPANS is gone, along with the assert_ne! tripwire that named it. The value it predicted — [(Q1,2), (None,1), (Q1,2), (None,1)] — is now what the test asserts, element for element. Sep is ungrouped, so the run ends before it and resumes under the second measure's own Q1 header; a precondition asserts the fixture still contains an ungrouped column, because without one the test cannot see a leaked group at all.

The superseded expectation — Q1 covering all six columns including the two under the ungrouped Sep, because expand_category emitted a header on entering a group and no boundary on leaving one, so the nearest-preceding walk kept answering Q1 — is recorded here because it is what AxisFrame::group_of answered before the fix, and the frame it was derived from still explains the current value. The frame is not one Q1 run — _Measure is the outer level, so the column axis is:

col_cats = ["_Measure", "Month"] Group(Q1) [Revenue,Jan] [Revenue,Feb] [Revenue,Sep] Group(Q1) [Cost,Jan] [Cost,Feb] [Cost,Sep]

Two Q1 headers, one per measure, and the ungrouped Sep sits inside each run rather than after both. So membership-correct spans are four runs, not two — and they do not coalesce across the second header, because Sep breaks the run between them. Hence [(Some("Q1"), 2), (None, 1), (Some("Q1"), 2), (None, 1)].

improvise-8qlr: the TUI arm was group_line.contains("▼ Q1"), which is one-directional and passes while the TUI labels every column. The run rule now lives once, as AxisFrame::group_runs/group_run_heads, and both ends call it; the TUI's group line is compared cell for cell against spans derived from the browser's own runs.

Fault injected exactly as that ticket specifies — forcing the TUI to emit the group label on every column (head = col_groups.get(ci), dropping the run-head lookup). Before: cargo test -p improvise stayed green. After: this test fails with ["▼ Q1","▼ Q1","","▼ Q1","▼ Q1",""] against ["▼ Q1","","","▼ Q1","",""].

One thing the shared rule does not flatten: the TUI labels its first visible column even mid-run, because a scrolled grid would otherwise draw an unlabelled group line. That is a scrolling concession, kept explicitly, and it is why the comparison is run at col_offset == 0.

#neither_front_end_produces_a_slash_joined_label

A separate assertion because the agreement tests above would also hold if both ends started slash-joining. This one is the bug's own words.

#the_collapse_state_crosses_as_a_fact_not_a_glyph

The group's collapse state reaches the browser as a fact, not as a glyph. The TUI spells it ▼/▶ (presentation, gotcha 26); the client gets the boolean and spells it however the DOM wants. Both states are checked, because a collapsed hard-wired to false would pass the first half. The non-empty precondition states the rule it depends on: a collapsed group still owes the user a header to expand again.

#src/ui/grid.rs

#render (helper)

The widget takes a GridCache, so the fixture builds one the way the TUI does: through an App, over the whole grid. Going through App rather than hand-rolling a cache is deliberate — these are characterization tests, and a handcrafted cache would test the widget against a fixture rather than against what the projection actually produces.

#grouped_model (helper)

A grid with a row group, a column group, a page axis and a total row, written against the pre-migration path (improvise-n10) so the move to GridCache is provably behaviour-preserving (doctrine(characterization_survives_the_move)). The fixture and GROUPED_FRAME are byte-identical to the pre-improvise-anr9 versions, which is what makes the comparison mean anything.

#the_whole_frame_is_unchanged

Asserts the exact buffer text, not a contains, because the facts it does cover — group indicator placement, column alignment, adaptive row-header width, the page bar, the totals strip — are all positional and a contains cannot see any of them.

What it does not cover, stated because an overclaim here is worse than a gap: Region is alone on Row and Month alone on Column, so both axes are single-level and this exercises no multi-level header and no repeat suppression — which is the whole subject of improvise-anr9. Widening the fixture would destroy the only byte-exact before/after evidence in that change, so it stays as it is; the multi-level agreement is tests/grid_frame_agreement.rs, which drives both front ends over a two-level, grouped fixture.

Re-pinned for improvise-0o6x. GROUPED_FRAME moved by exactly one line: the leading ▼ Co… header now draws above East, and everything below shifts down one. Nothing else in the buffer changed. That the group line, the column headers, the separator, the data rows and the totals strip are byte-identical is the evidence the change is the boundary condition it claims to be and not a reshuffle of the draw loop. It also fails alongside a_group_header_first_on_its_axis_reaches_both_front_ends when body_from's match is forced to false.

#two_row_categories_produce_cross_product_labels

Names the rendering the protocol must not carry: multi-level row headers show category values separately, never joined with /. It is the assertion tests/grid_frame_agreement.rs's module argument cites as the thing GridLayout::row_label violated.

#src/ui/import_wizard_ui.rs

#a_cut_inside_a_multibyte_character_does_not_panic

The bug, found by the PR #12 Copilot review and pre-existing on main: truncate sliced by byte index, so a cut landing inside a multi-byte character panicked. Every string it cuts can carry user input — a CSV column name, a formula being typed, an error message naming a field — so a document with an accented header crashed the TUI rather than eliding a name.

"Régions" is 8 bytes for 7 characters: the é occupies bytes 1..3, so max = 3 puts max - 1 = 2 inside it.

#no_cut_point_of_a_multibyte_string_panics

Not one cut point, every cut point. The interesting indices are the ones inside a character, and which those are depends on the string — so the test walks them rather than picking one and hoping it was the bad one. Each result must also be a prefix of the input, which is what says the boundary search walked down rather than dropping the character it landed in.

#ascii_truncation_is_unchanged

ASCII is unaffected, which is what lets the characterization fixtures in this file keep asserting exact frames written before the boundary fix.

#render (helper)

Drives a real ImportWizard and draws it through the projection, which is the whole path the TUI takes. Building the cache from the live wizard rather than by hand is deliberate: a handcrafted fixture would test the widget against the fixture instead of against what wizard_of actually produces, and the mapping is the half of improvise-764 most able to be silently wrong.

#every_step_draws_what_it_drew_before

Every step the wizard can draw, byte for byte. Written against the pre-migration path (improvise-764), where the widget reached into ImportWizard, ImportPipeline, FieldKind and Workbook directly, so the move onto a projected cache is provably behaviour-preserving (doctrine(characterization_survives_the_move)).

Exact text rather than contains: the interesting facts are positional — the column stops in the proposals table, where the hint line sits relative to the panel bottom, how far the date components are indented — and a contains sees none of them.

The walk is bounded and stops when advance no longer moves: the wizard's transitions are conditional (improvise-907) and a step that declines to advance must end the walk rather than spin it. NameModel is terminal for advance (gotcha 22) — the Enter there builds, and building is what parks the workbook on Done.

#the_formula_step_draws_its_transient_state

The transient bits of DefineFormulas: a formula in the list, one being typed, and a message overriding the hint line. Its FORMULA_STEP fixture is the one of the eight pinned frames that improvise-q0vb moved: it used to read something went wrongcel, the cel being the tail of Esc: cancel left behind because the message was written over a longer hint without clearing the rest of the row. The frame changing there was the point of that commit, not a side effect.

#a_message_shorter_than_the_hint_leaves_none_of_it

improvise-q0vb. The wizard's bottom row has two writers — the step's key hint and the message that overrides it — and set_string writes only as many cells as its string has. A message shorter than the hint therefore left the hint's tail beside it, and the artifact was pinned as correct output in FORMULA_STEP.

Asserted on ReviewProposals, whose hint is the longest in the wizard, so the tail it would leave is unmistakable. The precondition asserts the hint really is longer than the message — without it the test would pass on a step where there was nothing to leave behind.

#set_bottom_line_clears_every_cell_it_covers_and_no_more

The padding is in terminal cells, not characters (Copilot, PR #22). Buffer lays a string out by display width, so a chars().count() pad is wrong in both directions: a wide character counts one and occupies two, so the helper runs past the panel and over its right border; a combining mark counts one and occupies none, so the helper stops short and leaves cells it was supposed to clear.

Asserted against a sentinel, which is the correction Copilot made to a first version of this test. Drawing through the widget cannot see the under-padding case at all: the hint that ran first had already filled the row with its own padding, so the cells the combining message failed to reach held spaces rather than anything visible, and a "does the hint survive" assertion passed either way. The first version also looked like it had been proved, because the loop panicked on the wide-character case before ever reaching the combining one — doctrine(an_injected_fault_must_be_the_fault_you_named), from the other end.

So the test fills the row with X first and asks the helper directly: every interior cell must be the text or a space, and the two cells standing in for the panel border must still be X. Both faults are then visible as a surviving X — one inside, one outside.

#the_array_path_step_draws_its_candidates

One of the two steps the flat-array fixture skips. SelectArrayPath is reached by a document with more than one candidate array, which is also the only step that draws pipeline.array_paths.

#the_preview_step_draws_an_empty_document

WizardStep::Preview is the one step every_step_draws_what_it_drew_before never reaches (improvise-g6s1). Both fixtures there start at ReviewProposals or SelectArrayPath, and nothing advances into Preview — it is only ever an entry step, chosen by ImportWizard::new when the document needs no path selection and parses to zero records.

That left it the single arm where a change to wizard_cache could alter what is drawn with nothing failing, which is the same hole the other steps were pinned to close. An empty array is the smallest document that lands there.

It also puts on the record a wart the step has today: the summary ends Sample keys: with nothing after the colon, because there are no records to take keys from. Pinned as it is rather than quietly fixed — the point of a characterization fixture is that the next change to it is deliberate.

#tests/shipped_documents_load.rs

#every_shipped_document_loads

improvise-odbc. The finding behind it: bank-info.improv sat in the repo root for five months unable to parse — hand-edited through the v2025-04-09 format change rather than round-tripped, so its item lines carried bare names the grammar cannot spell (- JORDAN MARTINEZ) and its data lines named a category Measure the file declares as _Measure. Nothing loaded it, so nothing said so.

The grammar itself is covered far better than a fixture can manage, by the generator-driven proptests in improvise-io. What those cannot see is a checked-in document drifting out of the format, because they generate their inputs. This test is aimed at exactly that gap.

It is deliberately a directory walk rather than a list of names: a list is a second place to remember, and the file that gets forgotten is the one nobody added to it. The scope is the two directories .gitignore un-ignores — examples/ and web/; everything else matching *.improv is somebody's working file.

It matches on the full name, not on Path::extension(): .improv.gz is the same document gzipped and extension() calls it gz, so matching on the extension alone would skip it and put back the very hole this test exists to close.

#tests/web_demo_model.rs

#every_web_demo_cell_is_settable_except_the_column_a_formula_owns

improvise-bck. The demo document the standalone page opens must be one a visitor can type into, and the bug is not hypothetical: examples/demo.improv leaves Customer and Date on the None axis, so every cell in it is an aggregate over records the grid does not name, and an aggregate is not settable — correct behaviour, and a demo where the first thing a visitor clicks does nothing.

The question is asked exactly the way the browser asks it. ADR 002 says a cell is settable iff its CellId is Record, project::cell_id is the one place that decides, and render.rs::editable in the wasm client is that variant and nothing else (gotcha 42). So the test projects the demo's whole grid through grid_of — the same function the server calls per frame — and asserts on the surrogate, not on the axes. Asserting the axes instead would re-derive the rule and could agree with itself while disagreeing with the client.

It was proved discriminating by pointing it at examples/demo.improv, where it names the aggregate at (0,0).

improvise-ir7l renamed it, because the old name was false. The demo's third column is Profit = Revenue - Cost, and a formula target is a stored coordinate, so it projected Record and the page offered an editor over it — the test passed while its name was wrong for a third of the landing-page grid, which is exactly the shape this repo keeps finding. The assertion is now two-sided: the two raw columns must be Record and the Profit column must be CellId::Derived, so it fails if either half moves. Proved discriminating in both directions by deleting the derived branch of project::cell_id (Profit reads back as a Record) and, separately, by pointing it at examples/demo.improv again (the aggregate at (0,0) still fails it).

#the_web_demo_shows_a_formula_beside_its_inputs

The payoff a visitor should see without pressing a key: a formula column beside the two columns that feed it, so an edit visibly moves it. Profit at (0,2) is 18,400 - 6,200, recomputed on load.

#src/draw.rs

#release_kind_converts_like_press

The pre-conversion event loop never inspected KeyEventKind, so all kinds (Press/Repeat/Release) were dispatched. The conversion keeps that behaviour: a Release event converts like any other.

#The panel-migration equivalence tests (improvise-35e)

Each panel widget carries a pair: one test saying the inputs are unchanged by the move onto a projected cache, one pinning the drawing of them. The pair is the shape — a cache equivalence alone would not notice a changed renderer, and a rendered fixture alone would not notice the cache carrying different data.

#ui::tile_bar::tests::the_cache_carries_what_the_widget_used_to_read_off_the_model

#ui::formula_panel::tests::the_cache_carries_what_the_widget_used_to_read_off_the_model

Two tests share this leaf name, which is why both headings are qualified: one entry describes the pair, and an unqualified heading would have been satisfied by whichever of them the checker happened to see. The tile bar used to read view.tileable_cats(&model.category_names()) and view.axis_of(cat) off the model directly; the formula panel used to read model.formulas()[i].raw. Each now reads its cache, and a divergence is a rendering change nobody asked for.

#the_cache_reproduces_the_summary_the_widget_used_to_build

src/ui/view_panel.rs. The axis summary used to be built from workbook.views plus View::categories_on; it is now built from ViewSummary::axes. Same names, same order, same virtual-category filtering.

#the_active_view_summary_is_not_empty

The fixture must actually exercise the summary, or the equivalence above is two empty strings agreeing.

#examples/gen-grammar.rs

Not a test, but the generator the improvise-io proptests drive. It adds constraints beyond what the grammar requires, to produce realistic, round-trippable output rather than degenerate minima: bare names are drawn from a word pool instead of random letters, pipe_inner is never empty, rest_of_line always produces at least one character, and repetitions (*) produce 1–4 items rather than 0. Each invocation is seeded from the current time plus the PID.

#a_status_message_reaches_the_bottom_row_while_a_minibuffer_is_open

#the_minibuffer_prompt_is_not_displaced_by_the_message

#an_empty_message_never_pushes_a_row_that_fits_past_its_width

improvise-mai9. draw_bottom_bar rendered the minibuffer instead of the status line, so a message written while a text-entry mode was open was never drawn — not truncated, not overwritten. A test asserting app.status_msg was set passed in every one of those cases, which is how this survived improvise-6t3's careful effect ordering.

Of the ticket's two candidate fixes, the row is shared rather than the callers being made structurally unable to report: giving the status a second row changes frame geometry (improvise-q0vb's cost), and "always leave the mode before reporting" is what CommitSave does by hand and would have to be repeated at every text-entry commit — the thing the ticket calls a workaround.

The first version of these tests could not fail for the bug, and that is the entry worth reading. They called the composing helper minibuffer_line directly. The defect was in the wiring — draw_bottom_bar building its own format! and never consulting status_msg — so reverting that one line restored the bug in full with all 1411 tests green. The helper did not even go dead: the test module's use kept it alive while it asserted nothing about the product. Found by review (PR #77), reproduced here before rewriting.

So the guard is now Buffer-backed: a real Terminal<TestBackend> renders draw_bottom_bar and the assertion reads the row the terminal received. That is the only assertion that can fail for mai9's actual defect. Fault injected by restoring format!("{}{}", mb.prompt, buf) plus the cursor glyph — both wiring tests fail, the first naming the missing message and printing the row it did compose.

The second test exists because a "fix" that dropped to draw_status would satisfy the first on the message alone; it pins that the prompt still leads.

The third test is the negative arm, and its first version was unfalsifiable for arithmetic reasons. fill_line computes pad = width - left.len() - right.len(), so with an empty status an unconditional format!(" {msg} ") produces a byte-identical row at any width where the line fits: left plus width - left.len() spaces, either way. The match status_msg.is_empty() is observable only in the band where the prompt fits but left.len() + 4 does not — widths 16..=19 for this fixture, where the unguarded arm returns a row wider than the terminal.

That test then failed a second time in a more interesting way: it derived its lower bound by calling minibuffer_line itself, so the injected fault moved the bound with it and the loop skipped the failing band entirely. The bound is now spelled locally. A bound read off the function under test is not a bound — it is the fault grading its own exam.

Known and not fixed here: fill_line pads on left.len(), which is bytes, so the right-hand message sits two cells further right than intended whenever the left contains the multi-byte cursor glyph. draw_status has always done this with its own multi-byte content; it is pre-existing and out of scope. It is also what makes the band above four columns wide rather than two.

#a_group_header_first_on_its_axis_reaches_both_front_ends

improvise-0o6x. AxisFrame::body_from(idx) started at the first item, so at the top of the axis a leading FrameEntry::Group was skipped on the way to the screen — in both front ends. A collapsed group first on its axis therefore had its rows hidden and its header nowhere, so there was no affordance to get them back. The frame carried the header correctly; body_from dropped it.

It is a boundary condition, as the ticket suspected, but the boundary is not idx == 0. The windowing rule carries the nearest header ABOVE a scrolled window for group_of and body_from discards it — correctly. At the top of the axis there is no "above", and a frame cannot tell the two apart from idx alone, because the browser's frame is windowed and always passes 0. So AxisFrame gained first, the absolute data index of its first item, and the rule is first + idx == 0. Without it the browser would have drawn an extra header row at every scrolled position that the TUI does not.

This test is separate from the_two_front_ends_draw_the_same_row_header because that fixture orders Carol before Family to dodge this case on purpose, and says so. Both collapse states are driven: the uncollapsed arm alone passes against a frame that leads with a header only when it has items under it, which is the shape the windowing bug below produced.

The windowing half was found by this test and not predicted by the ticket. A collapsed leading group has NO item to carry its header into the window, so it reaches the frame only through axis_frame's pending queue — and a first version of the fix had GroupEnd clear pending above the window, which deleted exactly that header. GroupEnd is now queued like a header and clears nothing.

Fault injected by forcing body_from's match to false: this test fails and the_whole_frame_is_unchanged fails with it.

#two_abutting_runs_of_one_group_name_are_two_spans_at_both_ends

improvise-h0iv, end to end. The unit demonstration is in context/test-evidence/protocol.md; this is the same rule driven through a real GridLayout, a real project::grid_of and both renderers, because the reachability of the shape was itself in question.

two_level_rows has exactly h0iv's shape — Q1 grouping two of three months, cross-producted under two measures — and is saved by the ungrouped Sep between the runs, which is also what makes improvise-gd83's spans come out as [(Q1,2), (None,1), (Q1,2), (None,1)]. abutting_column_groups removes Sep and nothing else, so the two Q1 runs abut. The test asserts that no run is unlabelled before comparing anything: a fixture that grew an ungrouped column back would fail there rather than passing on the easy case.

It then compares the TUI's painted group line against the browser's runs exactly, which is the part that makes it an agreement test rather than a second assertion about group_runs.

Fault injected 2026-09-21: restoring the name-only comparison in AxisFrame::group_runs fails this with left: [(Some("Q1"), 4)] while the five existing agreement tests all pass — the ungrouped Sep in their fixture is precisely why they cannot see it.