Race conditions during process.env mutation in concurrent integration tests

Direct Answer

The recommended pattern is to avoid mutating process.env in tests altogether. Instead, run each test variant that requires a different environment in its own child process (via child_process.fork or spawn) with a custom env object, or refactor the system under test to accept configuration via dependency injection so it never reads process.env directly.

Why Global Mutation Fails Under Concurrency

• process.env is a single mutable object shared by the entire Node.js process.
• Parallel test runners (Jest, Vitest, Mocha with --parallel) execute multiple async tests in the same process.
• When Test A sets process.env.API_KEY=foo and Test B sets process.env.API_KEY=bar, the last write wins, causing non‑deterministic failures.

Native Alternatives That Work with --env-file

1. Child‑Process Isolation (Recommended)

Spawn a fresh Node process for each environment variant. The child inherits a copy of the parent’s environment but can be given a completely custom env map.

const { fork } = require('child_process');

function runTestWithEnv(envOverrides, testModule) {
  return new Promise((resolve, reject) => {
    const child = fork(testModule, {
      env: { ...process.env, ...envOverrides } // custom env for this test
    });
    child.on('message', resolve);
    child.on('error', reject);
    child.on('exit', (code) => code !== 0 && reject(new Error(`Exit ${code}`)));
  });
}

Each child process can still use --env-file at startup (e.g., NODE_OPTIONS='--env-file=.env.test' node child.js) because the flag is evaluated once per process.

2. Dependency Injection (Eliminates process.env Reads)

Pass configuration objects explicitly to the code under test:

// app.js
function createClient(config) { return { baseUrl: config.API_URL, token: config.API_TOKEN }; }
module.exports = { createClient };

// test.js
const { createClient } = require('./app');
test('uses test credentials', () => {
  const client = createClient({ API_URL: 'http://test', API_TOKEN: 'test-token' });
  expect(client.token).toBe('test-token');
});

This removes any reliance on process.env and makes tests fully parallel‑safe without process overhead.

3. Test‑Runner Process Isolation

• Vitest: pool: 'forks' with isolate: true (experimental) runs each test file in a separate process.
• Jest: Default testEnvironment: 'node' still shares process.env within a worker. True isolation requires a custom runner or spawning children manually.
• Mocha: Parallel mode (--parallel) runs in the same process; avoid it for env‑sensitive suites.

What Doesn’t Work for Parallel Tests

• Snapshot/restore (const old = {...process.env}; ...; process.env = old) – not atomic, async gaps allow interleaving.
• Worker threads – they share the parent’s process.env.
• dotenv / cross‑env / @dotenvx/dotenvx – all mutate the global process.env.
• --env-file – loads once at process start; cannot be changed per test without a new process.

Verification Steps

1. Write a minimal suite that runs 10+ async tests in parallel, each setting a unique process.env.TEST_VAR and asserting its value. Observe flaky failures.
2. Refactor one variant to use child_process.fork with a custom env and confirm deterministic results.
3. Check Node version: node --version (needs ≥20.6.0 for --env-file).
4. Consult your test runner’s docs for process‑isolation options.
5. Run the suite with and without the isolation pattern over multiple executions; compare flakiness rates.

One Missing Detail

Which test runner and version are you using? The exact isolation configuration (Vitest forks, Jest custom runner, Mocha serial mode) depends on that choice.