summaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
Diffstat (limited to 'docs')
-rw-r--r--docs/next-tests.md95
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.