Vitest timezone mocking: inconsistent Date behavior across environments

Answering the Question

Vitest does not ship a dedicated timezone‑mock API. The safest, most repeatable way to control Date behaviour across all environments is to explicitly set process.env.TZ for the duration of each test (or test file) and, when necessary, pair it with vi.setSystemTime(). This guarantees that both Node’s Date and libraries that rely on the process timezone (e.g., date‑fns‑tz) produce identical results regardless of the host’s default zone.

Why the Built‑In Mock Isn’t Enough

• vi.setSystemTime() freezes the epoch value but leaves the timezone unchanged.
• Changing process.env.TZ globally can leak between parallel workers unless we reset it after each test.
• Third‑party libraries that instantiate Date internally honour the current process.env.TZ at import time, so the mock must be in place before the module loads.

Confirmed Pattern

1. Capture the original timezone in a global setup file:

   // test/setup.ts
   const ORIGINAL_TZ = process.env.TZ;
   export { ORIGINAL_TZ };
   

2. Set the desired timezone before each test and restore it afterward:

   // test/example.test.ts
   import { vi } from 'vitest';
   import { ORIGINAL_TZ } from './setup';
   
   beforeEach(() => {
     process.env.TZ = 'UTC'; // or any zone you need
     vi.setSystemTime(new Date('2024-01-01T12:00:00Z'));
   });
   
   afterEach(() => {
     process.env.TZ = ORIGINAL_TZ;
     vi.useRealTimers();
   });
   

3. Import modules that depend on the timezone after the mock is in place. If a library is imported at the top of the file, move the import inside the test or use dynamic import:

   test('date‑fns‑tz works in UTC', async () => {
     const { utcToZonedTime, format } = await import('date-fns-tz');
     const zoned = utcToZonedTime('2024-01-01T12:00:00Z', 'America/New_York');
     expect(format(zoned, 'yyyy-MM-dd HH:mm')).toBe('2024-01-01 07:00');
   });
   

4. Run Vitest with a single worker for tests that import modules after the mock to avoid inter‑worker leakage:

   vitest --run --worker=1
   

5. For CI pipelines, set the TZ at the script level to provide a sane default:

   TZ=UTC vitest
   

Verification Checklist

• Run vitest --reporter=verbose locally and on CI; the output of new Date().toISOString() should match the mocked timezone.
• Check that process.env.TZ is restored after each test by adding a console log in afterEach.
• If a library caches the timezone string on first import, ensure you import it after setting process.env.TZ each time.

Missing Diagnostic Detail

Do your tests run with Vitest’s default parallel workers (multiple workers) or a single worker? This determines whether you need to isolate the process.env.TZ change per worker or can rely on a global reset after each test file.