summaryrefslogtreecommitdiff
path: root/docs/next-tests.md
diff options
context:
space:
mode:
authorGabriel Schneider <[email protected]>2026-11-03 16:04:46 -0300
committerGabriel Schneider <[email protected]>2026-11-03 16:04:46 -0300
commit86e9f8e241df16d96df542e08684af638c39fb89 (patch)
treeecfd1ecaa105e3a165493368d53566c912729ed9 /docs/next-tests.md
parent32d3ec7ea8bda6afc8614a100dfdc7421ecf76be (diff)
downloadpardes-86e9f8e241df16d96df542e08684af638c39fb89.tar.gz
pardes-86e9f8e241df16d96df542e08684af638c39fb89.zip
docs/next-tests.md: the behavioural-tests plan: tests through public surfaces only, so the code can be rewritten; the tiers (T1 in-process 9P, T2 a Zig process runner, T3 snap, T4 the window, perf gestures on the same input), the user's decisions, the inventory (722 of 1,686 tests reach into internals) and the surfaces missing, the phases
Co-Authored-By: Claude Opus 5.5 <[email protected]> Claude-Session: https://claude.ai/code/session_016Y9MNAtZenFv4weoMD3cge
Diffstat (limited to 'docs/next-tests.md')
-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.