1# Testing23One rule above the others: **a gate that did not judge may not say PASS.**4Every required test's inputs are committed to this repository or built by5the run itself. No required test skips, reads an `ATLAS_*` variable, or6looks in the home directory. CI enforces the first half of that7structurally: Go tests run through `tools/testgate`, which fails the run if8any test skipped, whatever the exit code said.910History, where it is needed, is a pointer rather than a chapter: the11pre-rewrite tree and its capture programs are archived on the12`golden-reference` tag (mirrored at `archive/golden-reference`), and the13behavioral differences accepted against it are14[decision 18](decisions/0018-divergences-from-the-reference.md).1516## The layers1718**`make test`** is the whole required surface, and what CI runs on19ubuntu, macOS and Windows (spelled step by step in20`.github/workflows/ci.yml`, because the Windows runner has no make):2122- `go vet ./...`, then `go run ./tools/testgate ./...` — every Go test in23 the module, skip-proof, with `-race` on the platform where a C toolchain24 is free.25- `npm run lane` and `npm run seam-lane` — each TypeScript lane's boundary26 rules, `tsc --strict`, and its own suite.27- `go run ./tools/depcheck` — the import matrix, hostenv purity, network28 confinement, semconv discipline.2930**`make test-e2e`** is the application in a real browser. The run builds31every one of its own prerequisites: the seam (`make static`), a registry32packed from the committed corpus (`tests/e2e/prep`), and the server33Playwright starts itself. The specs assert arrangement — URLs, the state34island, the topbar's controls, session memory — never pixels.3536**`make corpus-smoke`** is the maintainer's deep check and deliberately not37a CI gate: it walks a real installed library (`-bundles`, else38`$ATLAS_BUNDLES_DIR`, else the application's data directory) and holds39every current-format bundle to the reader's invariants. It compares no40stamps, no hashes and no content.4142## What tests are made of4344**Stated bundles.** The default. A test that needs a bundle writes one45through `format/bundle`'s real writer from a few lines of Go (see46`format/bundle/fixture_test.go`, `internal/workbench/bundles_test.go`) —47nothing opaque is committed, and a bundle a test measures is a bundle the48application could open.4950**The corpus** (`testdata/corpus/`). Real extractions, kept because their51provenance is public: bend-or is city open data, mars is NASA Trek. They52give the format, render, island and e2e suites real bytes with real depth —53multipart zones, described shapes, a sphere with two lenses — at the price54of about 14 MB. Public provenance is the bar for adding anything here; see55its README.5657**Hand-derived vectors** (`analysis/testdata/cells/`). The cell-system58contract, written down rather than recorded, and read by both59implementations of the arithmetic: the TypeScript lane's conformance suite60and the Go twin's (`tests/cells`). Until the planned unification deletes61one copy, these vectors are what keep the two from drifting.6263**Property tests** for what no single example can pin down: containment,64hierarchy, carry and plan-order invariants over invented locations in the65analysis lane; determinism in the pipeline (build twice, byte-identical);66fuzzing where bytes cross a trust boundary (`format/bundle`'s reader).6768## Where tests live6970Tests live with their package. Two trees exist because some tests cannot:7172- `tests/` — Go tests that need `os` against packages that may not73 (`hostenv` forbids `internal/app` the filesystem): `tests/island` drives74 the application's routes over the corpus, `tests/cells` reads the shared75 vectors, `tests/e2e` is the browser suite, `tests/corpus` the shared76 packer.77- `tools/` — the enforcement commands: `depcheck`, `testgate`,78 `corpussmoke`.7980## The bar for a new test8182Ask one question: what breaks if this test is deleted? A test that anchors83a number nobody can recompute, reads a path only one machine has, or skips84when the world is not to its liking does not clear it. State the bundle,85derive the expectation by hand, and if the inputs cannot be committed, the86check belongs behind `make corpus-smoke` — named as a maintainer's check,87not dressed as a gate.