KB / Memory / tech-bun-test-home-isolation

Bun writes .bun into a test fixture HOME — assert app state paths, not HOME emptiness

Bun creates ~/.bun (install/cache dirs) under whatever HOME is set when it runs, so hermetic tests must not assert an empty fixture HOME — assert the app-owned state dir is absent instead

reference
referencebuntestingisolationfixturesgotchahermetic
raw .md

When a test sets HOME to a fixture dir and spawns bun (e.g. bun --eval, bun run file.ts, or importing modules in a child), Bun may create <HOME>/.bun — its install/cache directory — inside the fixture, even when nothing installs.

Consequence: assertions like readdirSync(fixtureHome)).toEqual([]) fail with [".bun"], and before/after HOME snapshot comparisons are order-dependent (they pass only if an earlier test already created .bun).

Fix the invariant, not the fixture: the property under test is "the app wrote no state", not "HOME stayed empty". Assert the application-owned paths instead:

  • the app state dir under the fixture (~/.local/state/<app>) does not exist
  • the fixture cwd contains only the files the test wrote
  • pure-function paths: no draft/output JSON anywhere under the state dir

Never special-case .bun in an allowlist — that re-couples the test to Bun's cache layout. Related: bun test does not typecheck; don't present it as a typecheck gate.