Testing

Test Environment Isolation Strategies That Actually Work

HelpMeTest

HelpMeTest

— 6 min read
Test Environment Isolation Strategies That Actually Work

Flaky tests are rarely random. In most codebases, the cause is isolation failure: test A leaves state that breaks test B. When test A runs last in one execution order and first in another, B succeeds sometimes and fails other times. Teams call these tests "flaky" and treat them as an unfortunate fact of life. They're not — they're a symptom of shared mutable state between tests.

Isolation is the cure. An isolated test can run in any order, in parallel with any other test, any number of times, and produce the same result. Here's how to achieve that across every layer of your test stack.

Why Shared Test Environments Cause Flaky Tests

The most common isolation failures:

Database pollution. Test A creates a user with email test@example.com. Test B asserts that no user with that email exists. B passes when run first, fails when run second.

Shared counters and IDs. Tests that assert on auto-increment IDs (expect(user.id).toBe(1)) break as soon as any prior test has inserted a row.

Environment variable mutation. A test sets process.env.FEATURE_FLAG = "true" and never resets it. Subsequent tests see the flag enabled when they expect it to be disabled.

Port conflicts. Two test files each try to start a mock HTTP server on port 3001. The second one fails with EADDRINUSE.

Clock drift. Tests that depend on Date.now() without mocking the clock produce different results depending on when they run.

Each of these is solvable. Let's go through them layer by layer.

Database Isolation

Option 1: Transaction Rollback

The cleanest approach for tests that don't span multiple database connections is wrapping each test in a transaction that you roll back at the end. The test sees real database behavior (constraints, triggers, indexes) but nothing it does persists.

import { db } from '../src/db';
import { beforeEach, afterEach } from 'vitest';

let transaction: any;

beforeEach(async () => {
  transaction = await db.transaction();
  // Patch the db export to use this transaction
  jest.spyOn(db, 'query').mockImplementation(
    (sql: string, params?: any[]) => transaction.query(sql, params)
  );
});

afterEach(async () => {
  await transaction.rollback();
  jest.restoreAllMocks();
});

With Knex, this is more direct:

import knex from '../src/db/knex';

let trx: Knex.Transaction;

beforeEach(async () => {
  trx = await knex.transaction();
});

afterEach(async () => {
  await trx.rollback();
});

it('creates a user', async () => {
  const user = await createUser({ email: 'alice@example.com' }, trx);
  expect(user.id).toBeDefined();
  
  const found = await trx('users').where({ email: 'alice@example.com' }).first();
  expect(found).toBeDefined();
  // After this test, trx.rollback() removes the user
});

The limitation: this doesn't work if the code under test opens its own database connections outside the transaction (e.g., a background worker).

Option 2: Schema-Per-Test-Suite

Create a separate PostgreSQL schema for each test file (or test worker). All tables exist in all schemas, but each test suite operates in complete isolation:

// test/helpers/schema-isolation.ts
import { pool } from '../src/db';
import { randomBytes } from 'crypto';

export async function createTestSchema() {
  const schemaName = `test_${randomBytes(8).toString('hex')}`;
  
  await pool.query(`CREATE SCHEMA ${schemaName}`);
  await pool.query(`SET search_path TO ${schemaName}, public`);
  
  // Run migrations in this schema
  await runMigrations(schemaName);
  
  return schemaName;
}

export async function dropTestSchema(schemaName: string) {
  await pool.query(`DROP SCHEMA IF EXISTS ${schemaName} CASCADE`);
}

In your test setup:

let schemaName: string;

beforeAll(async () => {
  schemaName = await createTestSchema();
  // All subsequent queries in this worker use this schema
});

afterAll(async () => {
  await dropTestSchema(schemaName);
});

This is slightly heavier than transaction rollback but more robust — it works even when the code under test uses multiple connections or spawns async jobs.

Option 3: Database-Per-Worker

For the strongest isolation, give each parallel test worker its own database. This is particularly effective with Vitest's worker-based parallelism:

// vitest.config.ts
import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    pool: 'threads',
    poolOptions: {
      threads: {
        maxThreads: 4,
        minThreads: 1,
      }
    },
    globalSetup: './test/global-setup.ts',
  }
});
// test/global-setup.ts
import { Pool } from 'pg';

const adminPool = new Pool({ connectionString: process.env.DATABASE_ADMIN_URL });

export async function setup() {
  // Create one DB per worker
  const workerCount = parseInt(process.env.VITEST_WORKER_COUNT ?? '4');
  for (let i = 0; i < workerCount; i++) {
    await adminPool.query(`DROP DATABASE IF EXISTS testdb_worker_${i}`);
    await adminPool.query(`CREATE DATABASE testdb_worker_${i} TEMPLATE testdb_template`);
  }
}

export async function teardown() {
  for (let i = 0; i < 4; i++) {
    await adminPool.query(`DROP DATABASE IF EXISTS testdb_worker_${i}`);
  }
  await adminPool.end();
}

Workers pick up their assigned database via an environment variable that Vitest sets per worker:

// test/helpers/db.ts
const workerId = parseInt(process.env.VITEST_WORKER_ID ?? '0');
export const testDb = new Pool({
  connectionString: `postgres://user:pass@localhost/testdb_worker_${workerId}`
});

Service Isolation: Mocking External Dependencies

Port Allocation

Tests that start real HTTP servers conflict when they all try to bind to the same port. The fix: let the OS assign ports dynamically.

import { createServer } from 'http';

function getRandomPort(): Promise<number> {
  return new Promise((resolve, reject) => {
    const server = createServer();
    server.listen(0, () => {
      const port = (server.address() as any).port;
      server.close(() => resolve(port));
    });
    server.on('error', reject);
  });
}

let mockApiServer: http.Server;
let mockApiPort: number;

beforeAll(async () => {
  mockApiPort = await getRandomPort();
  mockApiServer = createMockApiServer();
  await new Promise<void>((resolve) => mockApiServer.listen(mockApiPort, resolve));
});

afterAll(async () => {
  await new Promise<void>((resolve) => mockApiServer.close(() => resolve()));
});

With msw (Mock Service Worker), you avoid ports entirely — interceptors run at the network layer:

import { setupServer } from 'msw/node';
import { http, HttpResponse } from 'msw';

const server = setupServer(
  http.get('https://api.stripe.com/v1/customers/:id', ({ params }) => {
    return HttpResponse.json({
      id: params.id,
      email: 'test@example.com',
      created: 1700000000,
    });
  })
);

beforeAll(() => server.listen({ onUnhandledRequest: 'error' }));
afterEach(() => server.resetHandlers());
afterAll(() => server.close());

The onUnhandledRequest: 'error' setting is critical — it catches tests that accidentally make real network calls, which is one of the most common sources of environmental interference.

Environment Variable Isolation

Never mutate process.env directly without restoring it:

// BAD — leaks into subsequent tests
beforeEach(() => {
  process.env.FEATURE_FLAG = 'true';
});

// GOOD — save and restore
let originalEnv: NodeJS.ProcessEnv;

beforeEach(() => {
  originalEnv = { ...process.env };
  process.env.FEATURE_FLAG = 'true';
});

afterEach(() => {
  process.env = originalEnv;
});

With Vitest, use vi.stubEnv which handles cleanup automatically:

import { vi, afterEach } from 'vitest';

afterEach(() => {
  vi.unstubAllEnvs();
});

it('enables new UI with feature flag', () => {
  vi.stubEnv('FEATURE_FLAG', 'true');
  // process.env.FEATURE_FLAG is 'true' only in this test
  expect(isNewUIEnabled()).toBe(true);
});

Clock Isolation

Tests that depend on the current time produce different results at different times of day, in different timezones, and on CI servers with clock skew. Always mock time:

import { vi } from 'vitest';

beforeEach(() => {
  vi.useFakeTimers();
  vi.setSystemTime(new Date('2024-01-15T10:00:00Z'));
});

afterEach(() => {
  vi.useRealTimers();
});

it('expires a session after 30 minutes', () => {
  const session = createSession();
  vi.advanceTimersByTime(31 * 60 * 1000); // advance 31 minutes
  expect(session.isExpired()).toBe(true);
});

Parallel Test Isolation in Vitest and Jest

Vitest Worker Scoping

Vitest runs each test file in its own worker thread by default. Resources created at the file level are automatically scoped to that worker. However, resources created in individual tests can still leak between tests within a file.

Enforce cleanup with Vitest's onTestFailed and onTestFinished hooks for resources that would otherwise require teardown in afterEach:

import { onTestFinished } from 'vitest';

it('processes a file upload', async () => {
  const tmpFile = await createTempFile('test-data');
  onTestFinished(() => fs.unlink(tmpFile)); // runs even if test fails
  
  const result = await processUpload(tmpFile);
  expect(result.size).toBeGreaterThan(0);
});

Jest Worker Configuration

Jest runs test files in separate worker processes. The number of workers defaults to the number of CPU cores minus one. To prevent resource exhaustion, limit worker count when each worker needs its own database:

// jest.config.js
module.exports = {
  maxWorkers: '50%', // Use half the CPU cores
  // or
  maxWorkers: 2,     // Fixed count matching your DB pool
  
  globalSetup: './test/global-setup.js',
  globalTeardown: './test/global-teardown.js',
  setupFilesAfterFramework: ['./test/setup.js'],
};

File System Isolation

Tests that read and write files conflict when they use the same paths. Use temporary directories:

import { mkdtemp, rm } from 'fs/promises';
import { tmpdir } from 'os';
import { join } from 'path';

let testDir: string;

beforeEach(async () => {
  testDir = await mkdtemp(join(tmpdir(), 'myapp-test-'));
});

afterEach(async () => {
  await rm(testDir, { recursive: true, force: true });
});

it('writes a report', async () => {
  const outputPath = join(testDir, 'report.json');
  await generateReport(outputPath);
  
  const report = JSON.parse(await readFile(outputPath, 'utf8'));
  expect(report.status).toBe('complete');
});

Each test gets a unique testDir like /tmp/myapp-test-a3f92c/. No collision is possible.

Measuring Isolation Quality

A practical check: run your test suite three times in random order and compare results. If results differ between runs, you have isolation failures.

Vitest supports randomized test ordering:

// vitest.config.ts
export default defineConfig({
  test: {
    sequence: {
      shuffle: true,
      seed: Date.now(), // Different seed each run
    }
  }
});

Jest equivalent with jest-shuffle:

npx jest --randomize

If tests that pass in sequence fail in random order, the failure message points directly to which test is polluting which. Fix the isolation — don't fix the order.

Read more