Testing
The app is tested with Vitest in a jsdom environment. Pure-function helpers, store actions, serialisation/compute math, and behavioural component tests (Testing Library) are all covered — there are no pixel/snapshot tests of styled output. This page documents the setup, the shared factories, and the gotchas to know before writing or debugging a test.
Commands
Section titled “Commands”| Command | What it does |
|---|---|
pnpm test |
One-shot run (vitest run), with a Node 24+ localStorage shim (see below). |
pnpm test:watch |
Watch mode. |
pnpm test:ui |
The Vitest UI. |
pnpm test:coverage |
Coverage run (vitest run --coverage --ui). |
cargo test |
Rust compute-layer tests from the repo root (workspace default-members = crates/zxw, so the cartographer submodule is skipped). |
cargo llvm-cov --workspace |
Rust coverage across the whole workspace. |
There is no separate typecheck script — TypeScript is checked through pnpm build and the VS Code
TS SDK.
Configuration
Section titled “Configuration”vitest.config.ts sets the environment and conventions:
- Environment:
jsdom— so tests can touchwindow,document, and React Testing Library’srenderHook. - Globals enabled —
describe/it/expectare available without importing (tests still import them for editor clarity). @/*path alias mirrorstsconfig.json, so tests resolve@/lib/...and@/store/...the same way the app does.include: ["src/**/*.test.{ts,tsx}"]— tests are co-located next to the code they cover.css: false— Tailwind classes are not processed in tests.
The localStorage gotcha
Section titled “The localStorage gotcha”The test script wraps vitest with a Node flag:
"test": "NODE_OPTIONS='--localstorage-file=/tmp/graph-board-test-localstorage' vitest run"This exists because Node ≥ 24 ships a native localStorage global that throws unless
--localstorage-file is passed — any test touching localStorage (the store’s hydrate/save,
the onboarding gate) would crash. jsdom provides its own working localStorage, but the Node
global can shadow it depending on isolation boundaries — hence the belt-and-braces setup in
vitest.setup.ts, which forces the global to jsdom’s implementation:
Object.defineProperty(globalThis, "localStorage", { value: window.localStorage, writable: true, configurable: true,});The setup file also pulls in @testing-library/jest-dom/vitest for matchers like
toBeInTheDocument and toHaveClass.
Test factories
Section titled “Test factories”src/test-utils/factories.ts centralizes the runtime VertexNode / GraphEdge shapes. Use
these in new tests so a future change to a type surfaces as one TS error in the factory, not ten
across test files.
Two vertex factories are provided, matching existing call-site conventions:
| Factory | Signature | Use it when |
|---|---|---|
makeVertex |
(id, position?, selected?) — positional |
The test cares about position/selection in that order (e.g. operations.test.ts). |
makeVertexWith |
(id, options?) — id first, then named options |
The test flips selection/data/rotation by name (e.g. graph-store.test.ts). |
makeVertex("a", { x: 10, y: 20 }); // positionalmakeVertexWith("a", { selected: true, data: { label: "$\\pi$", vertexType: "z" } });makeEdge("e1", "a", "b");Both stamp sensible defaults (vertexType: "z", origin: [0.5, 0.5], rotation: 0) so a test only
specifies what it cares about.
Conventions
Section titled “Conventions”What gets tested
Section titled “What gets tested”- Pure helpers and store actions are a primary surface — they’re fast, deterministic, and
where the real logic lives. Examples:
phase/parser.ts,graph/operations.ts,src/lib/serialisation/,store/graph-store.ts. - Components get behavioural tests. There is broad component coverage via React Testing
Library: render a component, interact with it, assert on the resulting DOM and store state —
but no pixel/snapshot tests of styled output (snapshotting a styled body pixel-for-pixel
isn’t worth the maintenance burden). Component tests assert on behaviour and structure (e.g.
VertexLabelEditor.test.tsxchecks the tag name and interaction, not exact CSS). - Async lazy-loaded modules need their chunk awaited. The KaTeX-path tests in
renderLabel.test.tsawait whenKatexReady()before asserting, becauserenderLabelreads a lazy-loaded KaTeX module synchronously and the chunk may not have resolved yet.
Co-location and naming
Section titled “Co-location and naming”- Tests sit next to their source:
foo.ts→foo.test.ts. - Large or cross-cutting edge-case suites go in a sibling
_edge_cases.test.tsfile (e.g.graph-store_edge_cases.test.ts,matrix-format_edge_cases.test.ts) to keep the primary test file readable.
Keeping the shortcut registry honest
Section titled “Keeping the shortcut registry honest”src/lib/keyboard/shortcuts.ts is a display-only registry; the real dispatch lives in
useKeyboardShortcuts.ts. shortcuts.test.ts asserts that every key the hook dispatches on also
appears in the registry, so the Help dialog can’t silently lie about a shortcut. If you add a
shortcut, add it to both files and the registry test will catch a miss.
Where this fits
Section titled “Where this fits”- Contributing — the commands and the “use the shared factories” rule in brief.
- Labels & Phases — why the KaTeX-path tests are async.