summaryrefslogtreecommitdiff
path: root/docs/typ/building.typ
diff options
context:
space:
mode:
Diffstat (limited to 'docs/typ/building.typ')
-rw-r--r--docs/typ/building.typ54
1 files changed, 32 insertions, 22 deletions
diff --git a/docs/typ/building.typ b/docs/typ/building.typ
index 41fadbb2..f78f83a9 100644
--- a/docs/typ/building.typ
+++ b/docs/typ/building.typ
@@ -77,6 +77,7 @@ must share with its session; `pardes --help` lists every flag.
zig build unit-test module and shell unit tests (the perf gate runs with it)
zig build test-build compile the unit-test programs without running them
zig build core-test core tests without native shell tests
+zig build shell-test the native shell's own unit tests, without the perf gate
zig build pane-test pane, output and namespace integration tests
zig build kitty-test kitty graphics conformance of terminal panes, at the core
zig build kitty-harness kitty graphics through a pane end to end (a fake kitty
@@ -84,18 +85,17 @@ zig build kitty-harness kitty graphics through a pane end to end (a fake kitt
kitten icat and chafa too when installed)
zig build syntax-test tree-sitter tests without building the editor
zig build syntax deterministic per-byte highlighting snapshots
-zig build behaviour-test behaviour through the 9P tree, in process (test/behaviour/)
-zig build process-test real sessions over their sockets: mounts, flags, shells (test/process/);
- -Dplatform=gui runs each case on the hidden window instead
+zig build behaviour-test behaviour through the 9P tree, in process (test/behaviour/),
+ and the T1 runner's short run of random 9P requests
+zig build process-test real sessions over their sockets: mounts, flags, shells (test/process/),
+ and the tty's own cases, each a pardes in a pty against its golden
+ (test/process/tty_*.zig, test/snapshots/); -Dplatform=gui runs the
+ socket cases on the hidden window instead
zig build monkey-gui random input to the hidden window, every effect setting (-Dplatform=gui)
-zig build gui-golden the hidden window's scenes against this machine's goldens (-Dplatform=gui)
-zig build monkey-session random in-process 9P requests checking the documented rules
zig build 9p-test freestanding protocol tests
zig build 9p-io-test native 9P transports and client
-zig build snap scripted input traces against frozen golden grids
-zig build monkey random snapshot scripts hunting panics (not a gate)
zig build hxdiff differential suite against helix's own behaviour
-zig build hxparity file-pane vs pty-pane editing parity
+ (-- --parity: each case in a file pane and a pty pane, which must agree)
zig build hxgolf every helix-golf example, step by step, against helix
zig build perf-gate a gesture on the 50k-line file over 3x its baseline fails
zig build mupdf-check the PDF addon's MuPDF: compile, link, render and search docs/design.pdf
@@ -104,18 +104,27 @@ zig build cheatsheet render the cheatsheet PDF (needs typst)
- `-Dtest-filter=<text>` applies to every unit-test binary. A failed test's
printed trace can be stale: run it alone with the filter.
-- `snap -- --record=DIR` writes snapshots without touching goldens,
- `snap -- --update` replaces goldens (re-record one script by name, after
- reading its diff, never all), `snap -- --no-retry` makes the first
- failure decisive. Snapshot scripts can use `snap9p` to capture core cells
- through 9P.
-- `zig build monkey -Dplatform=tui -- <seeds> [steps] [--from=N] [--out=DIR] [--keep]` writes one random script per seed and keeps any
- that panics; a seed always makes the same script. Each crash found gets a
- fix and a regression script in `test/snapshots/`.
+- `process-test -- <filter>` runs the cases whose name holds it (`tty
+ editing:` a family of the tty's, `tty editing: grep` one).
+ `process-test -- --update <filter>` writes a tty case's captures to its
+ golden: one case at a time, then a plain run, and read the golden's diff
+ for moved shell output (a flake) before keeping it. A tty case that fails
+ runs again alone with a wider settle probe before it counts; what it drew
+ is kept in `/tmp/pardes-snap/<name>/drew.golden`.
+- `behaviour-test -- --monkey <seeds> [--steps M]` types random keys, leader
+ bursts, mouse presses, drags, wheel turns and tiny resizes at an in-process
+ session, a seed a child, hunting panics and hangs; a seed always makes the
+ same input, and a failure is shrunk to the steps that make it. `-- --seed N`
+ runs the random 9P requests with the documented rules checked after each.
+ Each crash found gets a fix and a regression case.
+- `behaviour-test -- --replay` records each monkey seed's sessions as tapes
+ and replays them (three replicas and the dump); `process-test -- --replay
+ [--replay-with=<pardes-gui>]` records and replays the tty cases' real
+ sessions, their shells' and files' answers on the tape.
- The tutor's practice blocks (`# keys:`, `# before`, `# after` in
`src/tutor.txt`) are typed by hand; nothing runs them. What pins that
behaviour is `hxdiff`, which replays `test/hxcases` against goldens
- recorded from a real helix, and `hxparity`, which runs each case in a
+ recorded from a real helix, and its `--parity`, which runs each case in a
file pane and in a shell and demands they agree.
- `zig build hxdiff -- --strict cases.jsonl reference.jsonl [waivers.jsonl]` runs custom differential cases. `docs/helix-keys.md`
tracks helix parity key by key and names the reference helix build;
@@ -132,9 +141,10 @@ zig build cheatsheet render the cheatsheet PDF (needs typst)
== Release gates
A release passes all of these first: `unit-test` with `-Dplatform=tui` and
-with `-Dplatform=gui`, `core-test`, `behaviour-test`, `process-test`, `snap`, the GUI goldens
-(`zig build gui-golden -Dplatform=gui`, a hidden window; `PARDES_GUI_GOLDEN=update` rewrites them),
-and the ReleaseSafe tui and ReleaseFast gui builds. The committed
+with `-Dplatform=gui`, `core-test`, `behaviour-test`, `process-test` (on both:
+its tty cases on the tui, the hidden window on the gui), `hxdiff` and its
+`--parity`, the replicas harness and the soak (`test/soak.py`), and the
+ReleaseSafe tui and ReleaseFast gui builds. The committed
`docs/typ/cheatsheet-a4.pdf` is rendered again when the docs change.
= Sending patches <patches>
@@ -185,7 +195,7 @@ thing beside them (`edit.zig`, `normal.zig`, `look.zig`, `exec.zig`,
per-user daemon and a terminal's stub, `src/wire.zig` the input
wire a remote client will speak, `src/lsp/` the
language-server client; `test/` holds harnesses, goldens and helix cases,
-`build/` the snapshot suite's build step.
+`build/` the process tests' build steps.
== Threads
@@ -224,7 +234,7 @@ the terminal back and lets it go; the stub ends (exit 0) and the session
runs on with nothing drawn, until `pardes --attach` hands it another
terminal. A window's #word("Detach") closes the window and keeps the
process; `pardes-gui --attach` opens one again. `PARDES_DAEMON=off` (the
-snapshot harness) runs a session as before the daemon: in the terminal's
+process tests) runs a session as before the daemon: in the terminal's
own process, ended by its hangup.
A replica (a client running its own copy of the core, phase 5 of