summaryrefslogtreecommitdiff
path: root/docs/next-tests.md
blob: 9e234dfae7ff7b0ab8c910ea8d238ccb0f3dfa99 (plain) (blame)
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.