Skip to content

Replace the live dashboard with a Textual TUI - #46

Merged
lefticus merged 3 commits into
mainfrom
ui_improvements
Nov 18, 2026
Merged

lefticus merged 3 commits into
mainfrom
ui_improvements

Conversation

@lefticus

@lefticus lefticus commented Nov 17, 2026 •

Copy link
Copy Markdown
Member

--ui live is now a full-screen Textual app with tabs for the run, the survivors, every mutant, statistics and the log, driven by keyboard and mouse. Textual is a new optional ui extra. Without it, --ui live warns and prints plain output. The hand-drawn ANSI dashboard (dashboard.py, keys.py) is gone, so there is only one TUI.

What it shows

  • Header: phase badge with a spinner (or paused, stopping, finished), score with a sparkline of its history, totals counting each mutant once across tests, elapsed time, ETA and seconds per mutant.
  • Mutation map: one cell per mutant, coloured by result. Hover names the mutant; click jumps to it in the queue.
  • 1 Run: the current mutant as a syntax-highlighted diff, the queue with each result and its time, findings, and the build log. The queue can be browsed while the run continues; f follows the run again and enter opens the mutant's details.
  • 2 Survivors / 3 Mutants: a list beside the details (id, function, per-test coverage, which tests killed it or let it survive, a hint, the source). Mutants has clickable state filters.
  • 4 Stats: scores by file, operator and test, plus the slowest mutants.
  • 5 Log: the full console output.
  • Keys: p pauses before the next mutant, with sources unmutated. ctrl+c stops the run through the runner's existing KeyboardInterrupt path, so sources are restored and reports written. q leaves once the run has finished and prints the plain summary as before. ? lists every key; ctrl+p opens the command palette, which includes themes.
  • Toasts for new survivors and for the end of the run.

How it works

Textual needs the main thread, so Console.run(work) is new: the base class just calls work(), while TuiConsole runs the app on the main thread and the runner on a worker thread. The worker starts from the app's on_mount, so the runner never talks to an app that isn't running. The runner's console hooks update a thread-safe LiveState (strain/live_state.py, plain Python), and the app redraws from it every 100 ms, touching only what changed. SIGTERM and ctrl+c set a stop flag, and the runner's next console hook raises KeyboardInterrupt. If the user leaves the TUI mid-run, strain stops the run and waits for the sources to be restored before exiting.

Other changes

  • tests/test_tui.py: Pilot tests drive keys and mouse clicks headlessly (tabs, filters, map clicks, pause, quit, stop), plus TuiConsole lifecycle tests (result, error, stop, transcript replay). tests/test_live_state.py covers the state. The old dashboard and key tests are removed.
  • requirements-ci.in and requirements-ci.txt now include Textual, so CI runs the TUI tests instead of skipping them. Existing pins are unchanged.
  • tools/ui_snapshot.py can send mouse events (click:COL:ROW, scrollup:…, scrolldown:…) and has --delay to wait before sending keys.
  • CLAUDE.md, the README (new "Live TUI" section and screenshot) and the --ui help text are updated.

Relaxed safety nets

When a safety net fails but strain.toml or --safety-nets sets it to warn or ignore, the run goes on. Until now, the TUI showed that only as a passing warning, and an ignored net only as "missing but ignored by configuration", with no reason given. Now:

  • Header badge: ! N safety nets off. It's red when one of those nets errors by default, meaning a mutant that breaks the code can survive. Clicking it opens the report.
  • Safety nets panel at the top of Stats: for each relaxed net, the level it was set to and its default, where it fails, why it matters and the fix, followed by the nets that hold. When every net holds, the panel is one line and there's no badge.
  • Survivor caution: while a bug-hiding net is off, each survivor's details warn that it may survive only because of that, so it may point at the build rather than at a weak test.
  • Toast when the check runs.

classify_failures and RelaxedSafetyNet in safety_nets.py split the check into the errors that stop the run and the relaxed nets, which the console receives through a new safety_nets_checked hook. Plain output is unchanged.

Stats tab with asan and stdlib_assertions set to warn, ubsan and auto_var_init set to ignore (120x36)
  ◆ strain   all tests                                                                 ! 4 safety nets off   ✔ finished
 score 40.0% █▅▃▃▄▄▄   ✔ killed 2   ✗ survived 3   ○ ignored 1                             elapsed 0:08  ·  1.2s/mutant
 █████████████████████████████████████████████████████████████████████████████████████████████████████████████████ 6/6
 1 Run  2 Survivors 3  3 Mutants 6  4 Stats  5 Log
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╸━━━━━━━╺━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
╭─ Safety nets: 4 off ─────────────────────────────────────────────────────────────────────────────────────────────────╮
│ asan, ubsan, stdlib_assertions, auto_var_init are off, so a mutant that breaks the code can still pass the tests:    │
│ some survivors may point at the build rather than at a weak test. Fix the build before writing tests for them.       │
│                                                                                                                      │
│ ✗ asan  set to warn, so the run went on with a warning; by default it stops the run                                  │
│ fails      fails in 3 translation unit(s), e.g. /home/jason/mutant_strain/build/ui-relaxed/project/src/sample.cpp    │
│ why        without AddressSanitizer an out-of-bounds or use-after-free access introduced by a mutant can silently    │
│            read garbage and pass the tests, so the mutant survives even though the code is broken                    │
│ fix        add -fsanitize=address                                                                                    │
│                                                                                                                      │
│ ✗ ubsan  set to ignore, so the run went on without a warning; by default it stops the run                         ▆▆ │
│ fails      fails in 3 translation unit(s), e.g. /home/jason/mutant_strain/build/ui-relaxed/project/src/sample.cpp    │
│ why        without UBSan a mutant that causes signed overflow, an invalid shift or a null dereference is undefined   │
│            behavior that may happen to produce the expected result, hiding a real bug                                │
│ fix        add -fsanitize=undefined                                                                                  │
│                                                                                                                      │
│ ✗ stdlib_assertions  set to warn, so the run went on with a warning; by default it stops the run                     │
Survivor details with the caution row
  ◆ strain   all tests                                                                 ! 4 safety nets off   ✔ finished
 score 40.0% █▅▃▃▄▄▄   ✔ killed 2   ✗ survived 3   ○ ignored 1                             elapsed 0:08  ·  1.2s/mutant
 █████████████████████████████████████████████████████████████████████████████████████████████████████████████████ 6/6
 1 Run  2 Survivors 3  3 Mutants 6  4 Stats  5 Log
━━━━━━━╸━━━━━━━━━━━━━╺━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
╭─ Survivors 3 ────────────────────────────────╮╭─ src/sample.cpp:7:13  `<` → `<=` ────────────────────────────────────╮
│ location          op   change   survivor     ││ id         37a280a5  equivalent? list it under [ignore] mutants in   │
│ sample.cpp:7:13   ror  < → <=   not_reached  ││            strain.toml                                               │
│ sample.cpp:7:13   ror  < → >=   not_reached  ││ state      ✗ survived                                                │
│ sample.cpp:11:44  lcr  && → ||  not_reached  ││ operator   ror  < → <=                                               │
│                                              ││ function   clamp_to_zero(int)                                        │
│                                              ││ coverage   line 7 executed 1 time by sample_tests; 1/2 branches      │
│                                              ││            taken                                                     │
│                                              ││ caution    asan, ubsan, stdlib_assertions, auto_var_init off: this   │
│                                              ││            mutant may survive only because of that; 4 Stats          │
│                                              ││            explains                                                  │

Before and after

Before (old screenshot, 80x24):

before

After (120x36, Survivors tab, second survivor selected; this is the regenerated README screenshot, docs/images/tui-120x36.png):

after

Before: survivors view, 120x36 (ui_snapshot.py text)
strain live  ·  Test 2/2: other_tests  ·  finished                                           tab run  ↑↓ select  q quit
████████████████████ all tests 6/6  score 40.0%  killed 1  killed_by_sanitizer 1  survived 3  ignored 1
─ Survivors (3) ───────────────────────────────────────────────────────────────────────────────────────────────────────
  src/sample.cpp:7:13 [ror] `<` → `<=`  not_reached
▶ src/sample.cpp:7:13 [ror] `<` → `>=`  not_reached
  src/sample.cpp:11:44 [lcr] `&&` → `||`  not_reached
─ Survivor: src/sample.cpp:7:13 [ror] `<` → `>=` ──────────────────────────────────────────────────────────────────────
id         31b12689  equivalent? list it under [ignore] mutants in strain.toml
function   clamp_to_zero(int)
coverage   line 7 executed 1 time by sample_tests; 1/2 branches taken
survived   not_reached under sample_tests
hint       add a test input that takes the other branch

   1 │ #include "sample.hpp"
   2 │
   3 │ int add(int lhs, int rhs) { return lhs + rhs; }
   4 │
   5 │ int clamp_to_zero(int value)
   6 │ {
-  7 │   if (value < 0) { return 0; }
+  7 │   if (value >= 0) { return 0; }
   8 │   return value;
   9 │ }
  10 │
After: Run tab mid-run, 120x36
  ◆ strain   Test 1/2: sample_tests  ·  mutant 4/6                                               ⠇ running sample_tests
 score 33.3% █▅▃   ✔ killed 1   ✗ survived 2                                  elapsed 0:05  ·  eta 0:03  ·  1.3s/mutant
 ████████████████████████████████████████████████████████████████████████████░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ 3/6
 1 Run  2 Survivors 2  3 Mutants 3  4 Stats  5 Log
╸━━━━━╺━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
╭─ Mutant 4: src/sample.cpp:11:44  `&&` → `||` ──────────────────╮╭─ Mutants 3/6 ──────────────────────────────────────╮
│    4 │                                                         ││ state        location          op   change   time  │
│    5 │ int clamp_to_zero(int value)                            ││ ✔ killed     sample.cpp:3:40   aor  + → -    1.9s  │
│    6 │ {                                                       ││ ✗ survived   sample.cpp:7:13   ror  < → <=   1.0s  │
│    7 │   if (value < 0) { return 0; }                          ││ ✗ survived   sample.cpp:7:13   ror  < → >=   1.0s  │
│    8 │   return value;                                         ││ ▶ running    sample.cpp:11:44  lcr  && → ||        │
│    9 │ }                                                       ││ · pending    sample.cpp:13:49  aor  * → /          │
│   10 │                                                         ││ · pending    sample.cpp:15:38  aor  + → -          │
│ - 11 │ bool both(bool lhs, bool rhs) { return lhs && rhs; }    ││                                                    │
│ + 11 │ bool both(bool lhs, bool rhs) { return lhs || rhs; }    ││                                                    │
│   12 │                                                         ││                                                    │
│   13 │ int scale(int value, int factor) { return value * fact… ││                                                    │
│   14 │                                                         ││                                                    │
│   15 │ int offset(int value) { return value + 1; }// mutate-o… ││                                                    │
│   16 │                                                         ││                                                    │
│   17 │ Value *first(Value *values)                             ││                                                    │
│   18 │ {                                                       ││                                                    │
╰──────────────────────────────────── running sample_tests 0.8s ─╯╰────────────────────────────────────────────────────╯
╭─ Build log: cmake --build ../build --target sample_tests --p… ─╮╭─ Findings 3 ───────────────────────────────────────╮
After: Survivors tab, 120x36
  ◆ strain   all tests                                                                                       ✔ finished
 score 40.0% █▅▃▃▄▄▄   ✔ killed 1   ✔ killed_by_sanitizer 1   ✗ survived 3   ○ ignored 1   elapsed 0:08  ·  1.3s/mutant
 █████████████████████████████████████████████████████████████████████████████████████████████████████████████████ 6/6
 1 Run  2 Survivors 3  3 Mutants 6  4 Stats  5 Log
━━━━━━━╸━━━━━━━━━━━━━╺━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
╭─ Survivors 3 ────────────────────────────────╮╭─ src/sample.cpp:7:13  `<` → `>=` ────────────────────────────────────╮
│ location          op   change   survivor     ││ id         31b12689  equivalent? list it under [ignore] mutants in   │
│ sample.cpp:7:13   ror  < → <=   not_reached  ││            strain.toml                                               │
│ sample.cpp:7:13   ror  < → >=   not_reached  ││ state      ✗ survived                                                │
│ sample.cpp:11:44  lcr  && → ||  not_reached  ││ operator   ror  < → >=                                               │
│                                              ││ function   clamp_to_zero(int)                                        │
│                                              ││ coverage   line 7 executed 1 time by sample_tests; 1/2 branches      │
│                                              ││            taken                                                     │
│                                              ││ survived   not_reached under sample_tests                            │
│                                              ││ hint       add a test input that takes the other branch              │
│                                              ││ time       1.00s                                                     │
│                                              ││                                                                      │
│                                              ││    1 │ #include "sample.hpp"                                         │
│                                              ││    2 │                                                               │
│                                              ││    3 │ int add(int lhs, int rhs) { return lhs + rhs; }               │
│                                              ││    4 │                                                               │
│                                              ││    5 │ int clamp_to_zero(int value)                                  │
│                                              ││    6 │ {                                                             │
│                                              ││ -  7 │   if (value < 0) { return 0; }                                │

Testing

  • python -W error -m pytest: 254 passed, 9 skipped (the same skips as main; none of the TUI tests skip).
  • ruff format --check ., ruff check . and lizard --length 30 --warnings_only strain tests are clean.
  • Rendered the relaxed safety nets against a copy of the fixture built without sanitizers, assertions or -ftrivial-auto-var-init, with [safety_nets] set in its strain.toml.
  • Rendered against the fixture with tools/ui_snapshot.py at 120x36 and 80x24. Clicking a row and a tab in a real pty selects the survivor and switches the view.

Not tested: Windows and macOS terminals. Stopping takes effect at the next step boundary, so a long test run has to finish or time out first; a build is killed straight away.

🤖 Generated with Claude Code

lefticus and others added 3 commits November 17, 2026 18:41
`--ui live` is now a full-screen Textual app with tabs for the run, the
survivors, every mutant, statistics and the log, driven by keyboard and
mouse. Without Textual (the new `ui` extra) strain warns and prints plain
output; the hand-drawn ANSI dashboard and key reader are gone.

- Header: phase badge, score with its history, totals counting each mutant
  once, elapsed time, ETA and seconds per mutant.
- Mutation map: one cell per mutant colored by result; hover names it,
  click shows it in the queue.
- Run tab: syntax-highlighted diff, queue with per-mutant times that can be
  browsed while the run goes on, findings and the build log.
- Survivors and Mutants tabs: list beside full details; Mutants filters by
  state. Stats tab: scores by file, operator and test, slowest mutants.
- p pauses before the next mutant with sources unmutated; ctrl+c stops via
  the runner's KeyboardInterrupt path so sources are restored and reports
  written.

Textual needs the main thread, so the runner runs on a worker thread and
its console hooks update a thread-safe LiveState that the app redraws from.
ui_snapshot.py can send mouse events and wait before sending keys.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
When a safety net fails but its configured level is warn or ignore, the
run goes on: before, the TUI showed that only as a passing warning, and an
ignored net only as "missing but ignored by configuration". Now:

- The header shows a "! N safety nets off" badge, red when one of them
  errors by default; clicking it opens the report.
- Stats starts with a Safety nets panel: for each relaxed net, its level
  and default, where it fails, why it matters and how to fix it, then the
  nets that hold.
- While a net that hides bugs is off, each survivor's details carry a
  caution that it may survive only because of that.

classify_failures and RelaxedSafetyNet in safety_nets.py split the check
into the errors that stop the run and the relaxed nets the console hears
about through the new safety_nets_checked hook. Plain output is unchanged.
The README screenshot is regenerated from the final UI.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
test_tabs_switch_with_numbers_tab_and_the_mouse failed on CI now and then
because a view switch could undo itself, in two ways:

- Switching left focus on a widget in the old view. When that view hid,
  Textual moved focus to a neighbour there, and focusing a widget makes
  its view the active one, so the TUI jumped back.
- The startup activation message for the Run view could be handled after
  the first key press, and focusing the queue then switched back to Run.

Views now switch through show_view, which focuses the new view's widget
in the same step. The activation handler ignores a message for a view the
user has already left, and focuses a view only when focus is outside it,
as after a click on its tab.

New tests check that focus follows each switch and that a late activation
is ignored. Each fails reliably without its part of the fix. Other tests
are tightened: the small-terminal test asserts the view after each key, a
duplicate assertion is gone, and the queue test no longer focuses the
queue itself. ui_snapshot.py learns shift+tab.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@lefticus
lefticus merged commit 466aade into main Nov 18, 2026
11 of 12 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant