Grafema GraphSnapshot CI Friction
Problem
GraphSnapshot.test.js lives in test/unit/ and is picked up by the
test/unit/*.test.js glob used in pnpm test:coverage. Every feature PR that
intentionally changes graph output (new node types, edge types, column positions, etc.)
breaks this test — requiring a manual snapshot update cycle before CI goes green.
This creates a tax on every feature PR:
- CI fails with "Snapshot mismatch for 03-complex-async. Run UPDATE_SNAPSHOTS=true"
- Developer must: create worktree → pnpm install → pnpm build → UPDATE_SNAPSHOTS=true → run all tests → commit → push → wait CI again
- Repeat for each PR
Root Cause
Snapshot tests capture full graph output which changes on any intentional
behavior change. In an actively-developed codebase, this means they break on every
PR — they are not regression tests, they are progress blockers.
The pre-push hook compounds this by running pnpm build + pnpm snapshots:update
on every push (~2-3 minutes), even when snapshots aren't relevant.
Solution
Move the snapshot test outside the CI glob:
mkdir -p test/unit/snapshots
git mv test/unit/GraphSnapshot.test.js test/unit/snapshots/GraphSnapshot.test.js
The test/unit/*.test.js glob only matches files directly in test/unit/, not
subdirectories. The snapshot test now exists but won't run in CI.
Update package.json scripts (the glob stays unchanged — subdirectory exclusion
is automatic):
{
"snapshots:update": "UPDATE_SNAPSHOTS=true node --test --test-concurrency=1 test/unit/snapshots/GraphSnapshot.test.js"
}
Simplify the pre-push hook (.husky/pre-push):
#!/bin/sh
# Snapshots are excluded from CI (test/unit/snapshots/) and updated manually via:
# pnpm snapshots:update
When to Update Snapshots
Run pnpm snapshots:update manually when:
- Preparing a release and want to verify graph shape hasn't unexpectedly changed
- Merging a large refactor that touches multiple node/edge types
- Investigating a suspected silent regression in the graph structure
Current State (as of 2026-02-23)
test/unit/snapshots/GraphSnapshot.test.js — excluded from CI glob ✓pnpm snapshots:update — works for manual runs ✓.husky/pre-push — no-op (removed build+snapshot step) ✓
Trade-off
Losing: automatic detection of unintended graph shape changes in CI.
Gaining: every feature PR goes green without snapshot maintenance overhead.
Acceptable trade-off while graph shape is actively evolving. Revisit when the graph
API stabilizes — at that point, targeted invariant tests (not full snapshots) would
provide better regression coverage with less maintenance burden.