timezone-mock

1.4.2 verified Sat May 09 auth: no javascript

A JavaScript library to mock the local timezone for testing purposes. Version 1.4.2 is current stable, with infrequent releases. It replaces the global Date constructor with a mocked version that behaves as if in a specified timezone, including DST transitions. Key differentiators: lightweight, no dependencies, supports multiple timezones (US/Pacific, US/Eastern, Brazil/East, UTC, Europe/London, Australia/Adelaide) and GMT offsets, and includes TypeScript types. Unlike full timezone libraries, it focuses solely on mocking for testing, not on timezone conversions or comprehensive data.

Common errors

error TypeError: timezone_mock.register is not a function ↓

cause Importing default instead of named export (e.g., import timezoneMock from 'timezone-mock' then timezoneMock.register).

fix

Use import { register } from 'timezone-mock' OR import * as timezoneMock from 'timezone-mock' then timezoneMock.register.

error AssertionError [ERR_ASSERTION]: Expected values to be strictly equal. Expected: 1609459200000. Received: 1609455600000 ↓

cause Date comparison fails because mock timezone changes the timestamp for date string '2021-01-01T00:00:00' (interpreted as local time).

fix

Use UTC dates (new Date('2021-01-01T00:00:00Z')) or ensure consistent timezone handling.

Warnings

gotcha timezone-mock replaces the global Date constructor; if used in a test suite, must call unregister() after each test to avoid cross-test contamination. ↓

fix Use afterEach or cleanup hooks to call unregister().

breaking Node v8.0.0 changed ISO string 'YYYY-MM-DDTHH:MM:SS' from UTC to local interpretation. timezone-mock treats it as local, matching Node v8+; tests on older Node may behave differently. ↓

fix Ensure Node >= 8 for consistent behavior, or avoid date string parsing in tests.

deprecated Brazil/East timezone no longer observes DST as of 2019; DST transition only applies to dates 2018 and earlier. Using it for modern dates may not test DST correctly. ↓

fix Use US/Pacific or US/Eastern for DST testing.

gotcha Timezones Etc/GMT+X have inverted sign: Etc/GMT+5 is UTC-5, not UTC+5. Common mistake. ↓

fix Remember Etc/GMT+N = UTC-N, not UTC+N.

gotcha The _Date property is only available after register() is called; accessing it before results in undefined. ↓

fix Call register() first, then access timezone_mock._Date.

Install

npm install timezone-mock

yarn add timezone-mock

pnpm add timezone-mock

Imports

register

wrong

import timezoneMock from 'timezone-mock'; timezoneMock.register()

correct

import { register } from 'timezone-mock'

Package exports named exports; default import works but is not typical.

unregister

wrong

const { unregister } = require('timezone-mock'); // CommonJS works but ESM preferred

correct

import { unregister } from 'timezone-mock'

_Date
```
import { _Date } from 'timezone-mock'
```
Only available after register() is called; gives access to original Date.
options
```
import { options } from 'timezone-mock'
```
Accepts an object with fallbackFn for unparseable dates.

Quickstart

Demonstrates registering mock timezone, creating a Date, and unregistering. Also shows DST transition test.

import { register, unregister } from 'timezone-mock';

register('US/Pacific');
const date = new Date('2023-06-15T12:00:00');
console.log(date.getHours()); // Output may differ from local timezone
unregister();

// Test DST behavior
register('US/Eastern');
const dstDate = new Date('2023-03-12T02:30:00'); // DST transition
console.log(dstDate.getHours()); // 3 (spring ahead)
unregister();