1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
|
# 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:** test/snapshot.zig,
the `.snap` runner, which already forks the app in a pty and has a 9P
client (`snap9p`), grows 9P verbs (`9pwrite`, `9pexpect`, `signal`). The
Python suites (test/fs.py and the rest) stay as examples of scripting a
session and are not grown.
- **Layout (from a ponytail review, 2026-11-03):**
- **test/session.zig is the T1 `Session`:** a 9P client's walk, open,
read or write, clunk, by path, with the core opaque.
- **test/behaviour/<label>.zig holds the tests,** a file a section of
the book named by its label (`other-files` is other_files.zig), each
test's name its label first.
- **The `behaviour-test` step:** its module imports `session` alone, so
a behavioural test that reaches for `pardes` does not compile. That
boundary is the lint.
- **Expectations are inline;** goldens stay where they are.
- **A surface is added when a test being migrated needs one,** as a word in
a file that exists where it can be (a pane ctl's read already ends
`collapsed fit:… tint:…`; rio's wctl read is its window's rectangle).
- **A migration is one commit:** the behavioural test in, the M test it
replaces out, and the break it was checked against named. Phases 2 and 4
are one.
- **A replica's agreement is checked opt-in** (a Session option, to come),
for kbdin and mousein input, which a replica takes as events.
- **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 |
## Progress
Left to migrate, a file a row (`grep -c '^test "' <file>` before and
after; M as the inventory classed them):
| file | M at the start | moved | checked against |
|---|---|---|---|
| src/ninep/ctl.zig | 82 | 5 | `collapsed ` left off the ctl read; Putall saving nothing |
Migrated so far, in test/behaviour/: other_files (kbdin, mousein), panes
(collapsed, name's leading blank, Putall), edit (an Edit block to a pane's
ctl, the root's and exec, one left open at its clunk an err in the log).
## 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.
|