Skip to content

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.

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.

vitest.config.ts sets the environment and conventions:

  • Environment: jsdom — so tests can touch window, document, and React Testing Library’s renderHook.
  • Globals enabled — describe/it/expect are available without importing (tests still import them for editor clarity).
  • @/* path alias mirrors tsconfig.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 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:

vitest.setup.ts
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.

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 }); // positional
makeVertexWith("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.

  • 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.tsx checks the tag name and interaction, not exact CSS).
  • Async lazy-loaded modules need their chunk awaited. The KaTeX-path tests in renderLabel.test.ts await whenKatexReady() before asserting, because renderLabel reads a lazy-loaded KaTeX module synchronously and the chunk may not have resolved yet.
  • 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.ts file (e.g. graph-store_edge_cases.test.ts, matrix-format_edge_cases.test.ts) to keep the primary test file readable.

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.

  • Contributing — the commands and the “use the shared factories” rule in brief.
  • Labels & Phases — why the KaTeX-path tests are async.