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
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.