BE-319: Split backend integration tests into seeded and snapshot groups

[claude]

Requested by Tim Diekmann, Ahmad Sattar Atta · Slack thread

🌟 What is the purpose of this PR?

Follow-up to #9001, addressing review feedback: the boundary between tests that rely on the shared seeded graph and tests that wipe it was a path-prefix convention inside a single vitest run.

Before: one vitest run covered all test files, and a custom sequencer (DestructiveTestsLastSequencer) identified destructive files by the src/tests/subgraph/ path prefix and sorted them last. A destructive test added elsewhere would silently run mid-pack, wipe the graph seeded once per run by globalSetup, and corrupt the shared seed for every test file after it — the ordering was a convention, not a guarantee.

After: the suite is split into two explicit groups that run as separate, sequential vitest invocations:

• the seeded group (vitest.config.ts, src/tests/graph/) keeps the globalSetup seed and structurally cannot wipe the graph — its invocation contains no destructive file and completes before the destructive run starts;
• the snapshot group (vitest.snapshot.config.ts, src/tests/subgraph/) owns the wipe: it has no globalSetup, and its files reset the graph and restore standalone snapshots;
• a runtime guard enforces the boundary: resetGraph/restoreSnapshot throw a clear error unless the snapshot group's config marker is present, so a destructive call from the seeded group fails immediately in the offending file instead of corrupting unrelated tests.

The sequencer and the central registry file are gone; the groups are defined by the two configs over the existing directory layout (no test files were moved).

🔗 Related links

• Part of BE-319 (internal)
• Follow-up to BE-319: Seed the backend integration test graph once per run #9001 (review thread on the sequencer's path-prefix check)

🔍 What does this change?

All changes are in tests/hash-backend-integration:

• vitest.config.ts (seeded group): include is now only src/tests/graph/**/*.test.ts (18 files); keeps globalSetup. The DestructiveTestsLastSequencer and the src/tests/destructive-test-files.ts registry are deleted. Options common to both groups are exported as sharedTestConfig.
• vitest.snapshot.config.ts (new, snapshot group): includes only src/tests/subgraph/**/*.test.ts (3 files: circular, friendship, simple); no globalSetup; sets the HASH_TEST_GROUP=snapshot marker via vitest's test.env; writes coverage to ./coverage-snapshot so it doesn't clean the seeded group's ./coverage report (codecov's uploader discovers both).
• package.json: test:integration is now vitest --run && vitest --run --config vitest.snapshot.config.ts — seeded group first, snapshot group second. CI is unchanged: .github/workflows/test.yml invokes this via turbo run test:integration.
• src/tests/admin-server.ts: resetGraph() and restoreSnapshot() call assertRunningInSnapshotGroup, which throws unless process.env.HASH_TEST_GROUP === "snapshot". The error explains that destructive graph operations only run in the snapshot group and that a test file becomes destructive by placing it under src/tests/subgraph/. Other admin helpers (e.g. deleteUser, used by the seeded user.test.ts) are unguarded, as before. The module no longer imports from vitest, so it is usable outside a vitest worker again (no other consumers exist today — verified by grep).
• tsconfig.json: adds the new config file to include so tsc/typed eslint cover it.

Guard mechanism: in vitest 4.1.8, test.env from the config verifiably reaches process.env in test workers before any test file runs: the pool serializes env: { ...viteConfig.env, ...config.env } into the worker context, and the worker's setupCommonEnv writes each key through the metaEnv proxy, whose set trap assigns process.env[key] (verified in the installed vitest/dist/chunks/cli-api.*.js, setup-common.*.js, and init.*.js, and confirmed empirically with a scratch vitest run against the repo's installed vitest). In the seeded group's invocation the marker is simply never set, so the guard throws there.

Pre-Merge Checklist 🚀

🚢 Has this modified a publishable library?

This PR:

• does not modify any publishable blocks or libraries, or modifications do not need publishing

📜 Does this require a change to the docs?

The changes in this PR:

• are internal and do not require a docs change

🕸️ Does this require a change to the Turbo Graph?

The changes in this PR:

• do not affect the execution graph

⚠️ Known issues

• With coverage enabled, reports now land in two directories (coverage/ from the seeded run, coverage-snapshot/ from the snapshot run); the codecov action auto-discovers lcov files, so both are uploaded.
• src/tests/email.test.ts is matched by neither config — unchanged from main, whose include patterns (graph/** + subgraph/**) also excluded it.

🛡 What tests cover this?

The backend integration suite itself (yarn test:integration in tests/hash-backend-integration): the seeded group exercises the shared seed on every run, and the three snapshot-group files exercise the guard's pass path on every run.

Verification performed:

• tsc --noEmit and eslint for @tests/hash-backend-integration: the full dependency graph (wasm build, graph client codegen) cannot be built in my sandbox, so both were run on this branch and on main in the same unbuilt-deps state and the outputs diffed — byte-identical (pre-existing errors from unbuilt workspace deps on both; zero findings introduced by this change). oxfmt --check passes on all five changed files.
• vitest list --filesOnly run with both configs proves the partition: the seeded config lists exactly the 18 src/tests/graph/** files, the snapshot config lists exactly the 3 src/tests/subgraph/** files — no overlap, and together they cover every file the single config on main included.
• The test.env → process.env mechanism was verified in the installed vitest 4.1.8 dist and confirmed empirically (a scratch test asserting process.env.HASH_TEST_GROUP === "snapshot" passes under a config setting it via test.env).
• Not verified locally: an actual run of the suite — starting the graph stack is blocked in my sandbox (same limitation as BE-319: Seed the backend integration test graph once per run #9001). CI on this PR is the real verification.

❓ How to test this?

1. Checkout the branch
2. Start external services and the graph as usual, then yarn workspace @tests/hash-backend-integration test:integration — the seeded group runs first against the globalSetup seed, then the snapshot group runs the three subgraph/ files in a second vitest invocation.
3. To see the guard: add an await resetGraph() to any seeded-group test file — it fails immediately with an error explaining that destructive graph operations only run in the snapshot group (vitest.snapshot.config.ts) and how to place a test there.

---

Generated by Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
hash	Ready	Preview, Comment	Jul 10, 2026 1:21pm

2 Skipped Deployments

Project	Deployment	Actions	Updated (UTC)
hashdotdesign-tokens	Ignored	Preview	Jul 10, 2026 1:21pm
petrinaut	Skipped		Jul 10, 2026 1:21pm

[cursor]

PR Summary

Low Risk
Changes are limited to test harness configuration and guards in integration tests; no production runtime behavior is modified.

Overview
Backend integration tests are split into two sequential Vitest runs instead of one suite that relied on a custom sequencer to run destructive files last.

test:integration now runs the seeded group (vitest.config.ts, src/tests/graph/) and then the snapshot group (vitest.snapshot.config.ts, src/tests/subgraph/). Shared timeouts, parallelism, and setup live in sharedTestConfig exported from the main config.

The seeded config keeps globalSetup and only includes graph tests. The snapshot config has no globalSetup, sets HASH_TEST_GROUP=snapshot, uses a separate ./coverage-snapshot directory, and only includes subgraph tests.

resetGraph and restoreSnapshot in admin-server.ts now call assertRunningInSnapshotGroup, which throws unless that env marker is set—so graph wipes cannot run during the seeded invocation even if called from the wrong place.

^{Reviewed by Cursor Bugbot for commit 05656ce. Bugbot is set up for automated code reviews on this repo. Configure here.}