Testing says what make quick covers and what make check runs at once and alone, that e2e sessions run in parallel and wait rather than sleep, and when a golden screen is captured. The speed gate's section names the timed tests beside it; CLAUDE.md asks for one make check, at the end.
- commit
- 26dd53cc8d74359b261688fea7990b35ba0efff4
- parent
- 35f0f368feac91fef17b7dd52ae8f0ed5d7558cd
- author
- Dami <dami.etoile@gmail.com>
- kind
- docs risk score 0.0 of 3, Jev's estimate
| M | CLAUDE.md | 2 | + |
| M | docs/ | 4 | ++- |
| M | docs/ | 47 | ++++++++++++++++++++++++++---- |
@@ -12,6 +12,8 @@ Noise that stays becomes invisible, and then real problems hide in it.
1212 (staticcheck in every module, doclint, doccheck, cognitive complexity1313 at most 25, Go files at most 500 lines), unit tests, the excelize oracle and the1414 libghostty e2e tests. A red check is fixed first, not worked around.15+ Run it once, at the end, not repeatedly while iterating: `make quick`16+ checks just what changed ([testing](docs/contributing/testing.md#checking-a-change)).1517 - A warning is fixed where it points, or turned off in its tool's config1618 with the reason written next to it (`staticcheck.conf`). Nothing is left1719 standing because "it's always been there".@@ -733,7 +733,9 @@ too, well inside the margin; the margins are for regressions of a
733733 multiple, and finer ones are what `make stress-report` is for.734734 735735 The gate runs alone (`go test ./...` skips `TestSpeed` without736-`-speed`), and while it times it holds `/tmp/012-bench.lock`, the lock736+`-speed`), after the rest of `make check`, with the tests that time737+frames against fixed bounds, which `make test` leaves to it738+([Checking a change](testing.md#checking-a-change)). While it times it holds `/tmp/012-bench.lock`, the lock737739 other timed runs on the machine take: with flock(2) when the path is a738740 file (`flock /tmp/012-bench.lock make stress` where the `flock` command739741 exists), and otherwise as a directory it makes and removes, which needs@@ -6,11 +6,12 @@ sidebar_position: 5
66 # Testing77 88 ```sh9-make check # all of the below that must pass before a push: gofmt, vet, lint, test, speed, oracle, e2e10-make lint # go vet, staticcheck, cognitive complexity at most 25, Go files at most 500 lines, doclint and doccheck (see Docs below)11-make test # engine, file formats and UI unit tests9+make check # all of the below that must pass before a push: lint, test, oracle, e2e, then speed10+make quick # lint and tests of what changed, for iterating (see Checking a change below)11+make lint # gofmt, go vet, staticcheck, cognitive complexity at most 25, Go files at most 500 lines, doclint and doccheck (see Docs below)12+make test # engine, file formats and UI unit tests, but for the timed ones1213 make fuzz # fuzz the formula parser, random edits, and the .012, CSV, .wk1, XLSX and NUON readers13-make speed # frames and recalculation against a checked-in baseline (see limits.md)14+make speed # frames and recalculation against a checked-in baseline, and the tests that time frames (see limits.md)1415 make oracle # compare formulas and number formats with excelize1516 make e2e # run the real binary in a terminal emulator (needs Zig and pkg-config)1617 make screens # rewrite the golden screens and build the review gallery@@ -18,6 +19,26 @@ make stress # benchmarks on synthetic and real data (see limits.md)
1819 make site # build the docs site, failing on broken links (needs Node; see site.md)1920 ```2021 22+## Checking a change23+24+`make quick` is for iterating. It runs `make lint`'s Go checks and the25+unit tests of the packages changed since the branch left main,26+committed or not (`PKGS='./internal/sheet ./internal/ui/...'` names27+others), the oracle when it changed, and the e2e tests and golden28+screens defined in the e2e files that changed: all of e2e when the29+harness changed, or with `E2E=1`. It can't tell which e2e tests a change30+to `internal/` reaches; `make check` runs them all.31+32+`make check` is what must pass before a push. Run it once, at the end,33+not after every edit while iterating. It runs `make lint`, `make test`,34+`make oracle` and `make e2e` at once, each into a log of its own that35+it prints whole with the time it ended, then `make speed` on its own:36+the speed gate and the tests that time frames against fixed bounds37+(`TestSharedEditWithinAFrame`, `TestStreamGridAtFrameSpeed`,38+`TestScrollsAtFrameSpeed`), which `make test` leaves out so that no39+other tests share the CPU while they time. It takes about half a40+minute on an M5 Pro, most of it the e2e tests.41+2142 ## Unit tests2243 2344 The engine is tested directly: parsing, every function, recalculation,@@ -120,6 +141,14 @@ agent reads, suggests and asks, and the person accepts in the grid;
120141 live mode's screens attach it first (`screen.live`). Live mode's unit121142 tests (`internal/cowork`) attach the SDK's client over the socket.122143 144+Each test and each golden screen calls `t.Parallel`, so `make e2e` runs145+as many sessions at once as Go runs tests (`GOMAXPROCS`): every session146+is its own process and pseudo-terminal, in its own temporary directory147+with its own config and fake services. A test that shares something148+with others, or times keys (`TestStressKeyLatency`), leaves it out. On a149+machine this busy a frame can come late, so a test waits for what it150+checks (`waitFor`, `eventually`) and never sleeps for it.151+123152 `make e2e` builds libghostty-vt from source with Zig into `.deps/` on first124153 use. It is its own Go module so cgo never reaches the main binary.125154 @@ -129,7 +158,10 @@ use. It is its own Go module so cgo never reaches the main binary.
129158 cell grid (colors as palette variables, so one golden serves every theme),130159 with light-terminal variants. The states are listed in131160 `e2e/screenlist_test.go`, with the fixtures they share in132-`e2e/screensetup_test.go`. `make screens` rewrites them and builds161+`e2e/screensetup_test.go`. A screen is captured once it holds still162+and shows its golden, or once it has held still for five seconds without163+showing it: part of a screen can come after it first holds still, such164+as nu's highlighting on a busy machine. `make screens` rewrites them and builds133165 `e2e/testdata/screens/gallery.html` with dark and light reference palettes.134166 Every visual change is reviewed there before it's committed. It also135167 draws the docs' stills, the screens `docScreens` lists, into@@ -272,6 +304,7 @@ fail when they're stale.
272304 273305 ## No broken windows274306 275-`make check` must pass before a push, and warnings are fixed or turned276-off with a written reason rather than left standing. The rules are in307+`make check` must pass before a push ([Checking a change](#checking-a-change)),308+and warnings are fixed or turned off with a written reason rather than309+left standing. The rules are in277310 [CLAUDE.md](../../CLAUDE.md).