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
128
129
130
|
# 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 | 9, 1 X kept | `collapsed ` left off the ctl read; Putall saving nothing; a look's blanks trimmed; size taking a screen too small |
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),
look_and_exec (a look's leading blanks, a bare :N), columns_and_tags (a
look after Newcol), root_ctl (size). X, left where it is: a failure said
while a 9P write waits (it checks the 9P server's own flags).
## 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.
|