typescript-test-isolation-config-env-override

Answer

Root cause

dogfood004 used an afterEach snapshot-restore of the tracked duckbrain.config.json for test isolation. With vitest parallelism (pool: 'threads', fileParallelism: true), another worker's updateConfig() did a tmp+rename atomic write to the same shared file. Atomic rename prevents torn reads/writes, but not the logical race: worker B's rename lands after worker A's restore, so the next test observes a dirty config. Nondeterministic failures, only under parallel load.

Additionally, updateConfig() merged against an in-memory cached config loaded at module init. Once reads/writes are redirected via env, that cache is stale (loaded from a different file, or missing updates), so the merge base must be the raw file on disk.

Fix part 1 — DUCKBRAIN_CONFIG_PATH env override in getConfigPath

Mirrors the DUCKBRAIN_NAMESPACES_PATH precedent (BUG-037): read at runtime, env-only, never persisted — the override is never written into the config JSON and never serialized back to disk.

// src/config.ts
import fs from 'node:fs';
import path from 'node:path';

const DEFAULT_CONFIG_FILE = 'duckbrain.config.json';
export const CONFIG_PATH_ENV = 'DUCKBRAIN_CONFIG_PATH';

export interface DuckbrainConfig {
  version?: string;
  theme?: string;
  [key: string]: unknown;
}

/**
 * Env-only override, mirrors DUCKBRAIN_NAMESPACES_PATH (BUG-037).
 * Read at call time only; never persisted into the config JSON.
 * Lets tests redirect all reads/writes to a per-worker temp file.
 */
export function getConfigPath(): string {
  const override = process.env[CONFIG_PATH_ENV];
  return override ? path.resolve(override) : path.resolve(process.cwd(), DEFAULT_CONFIG_FILE);
}

/** Raw file content is the single source of truth — no cached merge base. */
function readRawFileConfig(filePath: string): DuckbrainConfig {
  try {
    return JSON.parse(fs.readFileSync(filePath, 'utf8')) as DuckbrainConfig;
  } catch (err) {
    if ((err as NodeJS.ErrnoException).code === 'ENOENT') return {};
    throw err;
  }
}

export function readConfig(): DuckbrainConfig {
  return readRawFileConfig(getConfigPath());
}

/**
 * Atomic tmp+rename write. Merge base is the *raw file content re-read from
 * disk at the current path* — never a stale in-memory snapshot — so concurrent
 * writers' changes are never lost and the env redirect can't mix file states.
 */
export function updateConfig(patch: Partial<DuckbrainConfig>): DuckbrainConfig {
  const filePath = getConfigPath();
  const raw = readRawFileConfig(filePath);      // re-read every time
  const next: DuckbrainConfig = { ...raw, ...patch };
  fs.mkdirSync(path.dirname(filePath), { recursive: true });
  const tmp = `${filePath}.${process.pid}.${Date.now()}.tmp`;
  fs.writeFileSync(tmp, JSON.stringify(next, null, 2) + '\n');
  fs.renameSync(tmp, filePath);                 // atomic: readers see old or new, never partial
  return next;
}

/** Snapshot/restore helpers used by dogfood004's isolation pattern. */
export function snapshotConfig(): string {
  return fs.readFileSync(getConfigPath(), 'utf8');
}
export function restoreConfig(snapshot: string): void {
  fs.writeFileSync(getConfigPath(), snapshot);
}

The critical updateConfig change: { ...raw, ...patch } where raw is re-read from disk per call. The old code merged against a module-level cache ({ ...cached, ...patch }), which under the env redirect pointed at the wrong file / stale content.

Fix part 2 — test-setup.ts per-worker temp-config redirect

// test/test-setup.ts
import fs from 'node:fs';
import os from 'node:os';
import path from 'node:path';
import { afterAll } from 'vitest';
import { CONFIG_PATH_ENV } from '../src/config';

// vitest guarantees setupFiles run before any test-file module evaluation,
// so setting this env var here is safe even for `import`-time getConfigPath().

// mkdtemp => unique file per worker: parallel workers never share a config file.
const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'duckbrain-config-'));
const tempConfigPath = path.join(tmpDir, 'duckbrain.config.json');

// Seed a pristine baseline from the repo fixture; the tracked file is only
// ever *read* during tests, never written.
const fixturePath = path.resolve(process.cwd(), 'duckbrain.config.json');
if (fs.existsSync(fixturePath)) {
  fs.copyFileSync(fixturePath, tempConfigPath);
} else {
  fs.writeFileSync(tempConfigPath, '{}\n');
}

process.env[CONFIG_PATH_ENV] = tempConfigPath;

afterAll(() => {
  delete process.env[CONFIG_PATH_ENV];          // env-only: never leak past the run
  fs.rmSync(tmpDir, { recursive: true, force: true });
});

Fix part 3 — wire the setup file

// vitest.config.ts
export default defineConfig({
  test: {
    setupFiles: ['test/test-setup.ts'],
    pool: 'threads',
    fileParallelism: true, // parallel execution now safe: per-worker temp files
  },
});

With this, worker A's dogfood004 snapshot/restore and worker B's updateConfig() operate on disjoint temp files. The tracked duckbrain.config.json is byte-identical before and after any test run — the race is structurally impossible, not just improbable.