summaryrefslogtreecommitdiff
path: root/docs/next-tests.md
blob: 3f85e0302b5744ad96977b80d0ba46ea33702fe9 (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
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
# 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

After the first fan-out (2026-11-03: four migrators, each followed by a
reviewer that ran its own breaks; 108 tests in test/behaviour/):

| area | moved | M left | X kept |
|---|---|---|---|
| src/ninep/ctl.zig, pane.zig | 38 (9 by hand) | about 72 | 6 |
| test/panes.zig | 30 | 15 | 16 |
| src/pardes.zig | 28 | 17 | 36 |
| test/pdf.zig, test/output.zig | 14 | 28 | 13 |

What the M left need, most first:
- **Effects performed:** Session counts a save and drops it; a save
  record, /recent after a save, and a terminal's pty bytes come only once
  a host performs the effect. A Session option that performs saves (and
  keeps pty writes) unlocks a group in each area.
- **A real host (T2):** terminals' output and shells, command panes
  finishing, Tty and pty/ctl exec, a missing interpreter.
- **Image panes:** they need the decoder worker Session does not start.
- **LSP:** a fake language server.
- **Not reached yet:** jumps and Back/Forward, Zerox, Get, Restore,
  DumpConfig, ThemeFile, and name edge cases.

Traps the migrators found in Session, each now in its tests' code:
- **It never ticks the core,** so a record a step makes (a pane's `new`)
  shows in /log only at the next request.
- **A last line with no newline is held until the clunk;** its failure
  goes to /log only, and the write reports success. End ctl lines with
  `\n`.
- **`write` appends (`>>`); `replace` truncates first (`>`).**
- **`read` sets no `said`.**

## Phases
## 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.