diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/next-tests.md | 95 |
1 files changed, 95 insertions, 0 deletions
diff --git a/docs/next-tests.md b/docs/next-tests.md new file mode 100644 index 00000000..f05a6e73 --- /dev/null +++ b/docs/next-tests.md @@ -0,0 +1,95 @@ +# Behavioural tests: free to rewrite the code + +> I think we need a larger project to turn most of the tests into +> behavioural ones so that we are free to rewrite the code. + +Planned 2026-11-03 by the user and the coordinator, from an inventory +agent's survey. The `e2e` line (kbdin, mousein) is its first step. + +## Decided by the user + +- **A test goes in and comes out through public surfaces only:** the 9P + tree (pane files, `ctl`, `look`/`exec`, `log`, `/screen`, `kbdin`, + `mousein`), the process (flags, daemon, attach, signals, terminal bytes), + and files on disk and effects. A rewrite that keeps those keeps its tests. +- **T1, in-process 9P, is the main tier.** The core is driven only through + `serveFs` (src/ninep/testing.zig's `call`, `rd`, `wr`): as behavioural + as a client on a socket, and milliseconds a case. +- **Process-level tests (T2) get a Zig runner, not Python.** The Python + suites (test/fs.py and the rest) stay as examples of scripting a session + and are not grown. +- **Later, not now:** + - The reference as the spec: one test per documented behaviour, named by + its section (docs/typ/reference.typ for the 9P surface, guide.typ and + the cheatsheet for keys and mouse). A sample of 20 reference rows found + 18 in some test; `restoredcol` and the EROFS mapping in none. + - Phase 2 as a multi-agent workflow, an agent per area and a reviewer. + +## Tiers + +| tier | drives | for | +|---|---|---| +| T1 | the core through `serveFs`, in process | most behaviour; each case also through a replica that must agree | +| T2 | a real `pardes` over its socket, a Zig runner | daemon, attach, mounts, shells, flags | +| T3 | terminal bytes, the `.snap` scripts | tty rendering and keys | + +| T4 | the window: `pardes-gui` hidden (`PARDES_TEST`, offscreen), its input through the same 9P files, frames captured once its status file says idle | what only pixels show | +| perf | T1 or T4 gestures, timed | latency gates against baselines | + +The window (T4): its core is the one T1 drives, so a behaviour the cells +show is tested at T1; T4 is for what only pixels show (scene effects, +images, fonts, edges). test/gui_golden.py's 17 frame hashes +(test/gui-goldens.txt) are an exact gate for one machine, never a CI one, +and move to the Zig runner with T2. gui.zig's own tests: 19 M, 17 B, 47 U. + +Performance: test/perf.zig times gestures through `update` and `render` +with a few internal reads (12), against test/perf-baseline-*.json (the +perf-gate step); the PDF, rollback, locations and fs benches time +components. A gesture is to be written as T1 or T4 input (kbdin, mousein), +so a rewrite is timed by the same case it is tested by; a bench of one +component stays a U-level bench of that component. + +U tests (a stable library at its own pub functions with no core: regexp, +diff, sam addresses, walk, wire, Text, modal's parse) stay as they are. + +## Inventory (2026-11-03, a regex classifier: about ±15%) + +| class | tests | lines | +|---|---|---| +| B, behavioural already | 252 | 6.3k | +| U, a library's unit | 682 | 15.4k | +| M, to migrate | 722 | 26.7k | +| X, pinned to the implementation | 30 | 1.6k | + +Most M: pardes.zig 116, test/panes.zig 104 (of 124), ninep/ctl.zig 82 +(in through 9P, checked through `p.panes`), test/output.zig 34, +ninep/pane.zig 28, test/pdf.zig 25. + +What the M tests reach into, and the public surface for it: + +| internal | tests | surface | +|---|---|---| +| `p.active` | 242 | `/focus` | +| a file's text | 173 | `pane/n/body` | +| `body.cur_*`, `sel` | 126 | `dot`, `sel`, `addr` | +| path, dirty | 121 | `name`, `dirty`, `/index` | +| click cells from `p.rects` | 158 | **missing**: pane geometry | +| `body.mode` | 90 | **missing**: a mode file | +| Alt, Shift keys | 18 | **missing**: modifiers in `kbdin` | +| notices, places | 28 | **missing** | +| `.pdf.?` | 25 | **missing**: page, viewport | +| terminal cursor, overlay | 60 | partial | + +## Phases + +0. Inventory. Done, above. +1. The T1 `Session` API (open, type, click, read pane files and screen + text, expect; through a replica too), the missing surfaces in the + table's order, and a lint that fails a behavioural test touching + `p.panes[`, `.file.?`, `p.rects` and the like. +2. Migrate, in the order the code is to be rewritten: ninep/ctl.zig (its + checks only), test/pdf.zig (step 3 of the pane-kinds plan), + pardes.zig and test/panes.zig, replica, the gui and tty shells, + host_io. A migrated test must fail on a build broken on purpose. +3. Gaps: a test for each documented behaviour with none. +4. Delete the M and X tests the new ones cover. |
